diff --git a/README.md b/README.md index 3e3a63a..19d9bce 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ This allows you to use all the useful - [Installation](#installation) - [With TypeScript](#with-typescript) - [Usage](#usage) + - [Differences from DOM Testing Library](#differences-from-dom-testing-library) - [Other Solutions](#other-solutions) - [Contributors](#contributors) - [LICENSE](#license) @@ -95,7 +96,7 @@ and should be added as follows in `tsconfig.json`: Add this line to your project's `cypress/support/commands.js`: -``` +```javascript import '@testing-library/cypress/add-commands' ``` @@ -105,28 +106,66 @@ and `queryAllBy` commands. You can find [all Library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts). +To configure DOM Testing Library, use the following custom command: + +```javascript +cy.configureCypressTestingLibrary(config) +``` + To show some simple examples (from [cypress/integration/query.spec.js](cypress/integration/query.spec.js) or [cypress/integration/find.spec.js](cypress/integration/find.spec.js)): ```javascript -cy.queryByText('Button Text').should('exist') -cy.queryByText('Non-existing Button Text').should('not.exist') -cy.queryByLabelText('Label text', {timeout: 7000}).should('exist') -cy.findAllByText('Jackie Chan').eq(0).click(); +cy.queryAllByText('Button Text').should('exist') +cy.queryAllByText('Non-existing Button Text').should('not.exist') +cy.queryAllByLabelText('Label text', {timeout: 7000}).should('exist') +cy.findAllByText('Jackie Chan').click(); + +// findAllByText _inside_ a form element cy.get('form').within(() => { - cy.findByText('Button Text').should('exist') + cy.findAllByText('Button Text').should('exist') }) cy.get('form').then(subject => { - cy.findByText('Button Text', {container: subject}).should('exist') + cy.findAllByText('Button Text', {container: subject}).should('exist') }) +cy.get('form').findAllByText('Button Text').should('exist') ``` +### Differences from DOM Testing Library + `Cypress Testing Library` supports both jQuery elements and DOM nodes. This is necessary because Cypress uses jQuery elements, while `DOM Testing Library` expects DOM nodes. When you pass a jQuery element as `container`, it will get the first DOM node from the collection and use that as the `container` parameter for the `DOM Testing Library` functions. +`get*` queries are disabled. `find*` queries do not use the Promise API of +`DOM Testing Library`, but instead forward to the `get*` queries and use Cypress' +built-in retryability using error messages from `get*` APIs to forward as error +messages if a query fails. `query*` also uses `get*` APIs, but disables retryability. + +`findAll*` can select more than one element and is closer in functionality to how +Cypress built-in commands work. `findAll*` is preferred to `find*` queries. +`find*` commands will fail if more than one element is found that matches the criteria +which is not how built-in Cypress commands work, but is provided for closer compatibility +to other Testing Libraries. + +Cypress handles actions when there is only one element found. For example, the following +will work without having to limit to only 1 returned element. The `cy.click` will +automatically fail if more than 1 element is returned by the `findAllByText`: + +```javascript +cy.findAllByText('Some Text').click() +``` + +If you intend to enforce only 1 element is returned by a selector, the following +examples will both fail if more than one element is found. + +```javascript +cy.findAllByText('Some Text').should('have.length', 1) +cy.findByText('Some Text').should('exist') +``` + ## Other Solutions I'm not aware of any, if you are please [make a pull request][prs] and add it diff --git a/cypress/.eslintrc b/cypress/.eslintrc new file mode 100644 index 0000000..352fd0c --- /dev/null +++ b/cypress/.eslintrc @@ -0,0 +1,6 @@ +{ + "rules": { + "max-lines-per-function": "off", + "jest/valid-expect-in-promise": "off" + } +} diff --git a/cypress/fixtures/test-app/index.html b/cypress/fixtures/test-app/index.html index 42a4b7e..36a3fc3 100644 --- a/cypress/fixtures/test-app/index.html +++ b/cypress/fixtures/test-app/index.html @@ -29,6 +29,9 @@

*ByLabel and *ByPlaceholder

+ +

Intentionally inaccessible label for error checking

+

*ByText

@@ -89,6 +92,24 @@

*AllByText

*ByText on another page

Next Page
+
+

Eventual existence

+ + +
+
+

Eventual non-existence

+ + +