intro.mdx

id	title
intro	Cypress Testing Library

Cypress Testing Library allows the use of dom-testing queries within Cypress end-to-end browser tests.

npm install --save-dev cypress @testing-library/cypress

• Cypress Testing Library on GitHub

Usage

Cypress Testing Library extends Cypress's cy commands.

Add this line to your project's cypress/support/commands.js:

import '@testing-library/cypress/add-commands';

You can now use all of DOM Testing Library's findBy, findAllBy, queryBy and queryAllBy commands off the global cy object. See the DOM Testing Library docs for reference.

Note: the get* queries are not supported because for reasonable Cypress tests you need retryability and find* queries already support that. query* queries are no longer necessary since v5 and will be removed in v6. find* fully support built-in Cypress assertions (removes the only use-case for query*).

With TypeScript

Typings should be added as follows in tsconfig.json:

{
  "compilerOptions": {
    "types": ["cypress", "@testing-library/cypress"]
  }
}

You can find all Library definitions here.

Examples

To show some simple examples (from cypress/integration/find.spec.js):

cy.findByRole('button', { name: /Jackie Chan/i }).click()
cy.findByRole('button', { name: /Button Text/i }).should('exist')
cy.findByRole('button', { name: /Non-existing Button Text/i }).should(
  'not.exist'
)
cy.findByLabelText(/Label text/i, { timeout: 7000 }).should('exist')

// findAllByText _inside_ a form element
cy.get('form')
  .findByText('button', { name: /Button Text/i })
  .should('exist')
cy.findByRole('dialog').within(() => {
  cy.findByRole('button', { name: /confirm/i })
})

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.