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.

Last updated on by Pete Nykänen