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


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 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.


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
.findByRole('button', {name: /Button Text/i})
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.