Skip to main content

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

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 some of DOM Testing Library's findBy, and findAllBy commands off the global cy object. See the About queries 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')

// findByRole _inside_ a form element
cy.get('form')
  .findByRole('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.