@testing-library/cypress

What is @testing-library/cypress?

@testing-library/cypress is an extension of the Testing Library family for use with Cypress, a popular end-to-end testing framework. It provides a set of custom commands for interacting with DOM elements in a way that resembles how users interact with your application, making tests more readable and maintainable.

What are @testing-library/cypress's main functionalities?

Querying Elements

This feature allows you to query DOM elements using the same queries available in @testing-library/dom. For example, you can find a button with the text 'Submit' and click it.

cy.findByText('Submit').click();

Assertions

You can make assertions on elements found using Testing Library queries. This example checks if a button with the role 'button' and name 'submit' is visible.

cy.findByRole('button', { name: /submit/i }).should('be.visible');

Custom Commands

The package provides custom commands like `findByLabelText` to interact with form elements. This example types 'myUsername' into an input field labeled 'Username'.

cy.findByLabelText('Username').type('myUsername');

Other packages similar to @testing-library/cypress

cypress-testing-library

cypress-testing-library is another package that integrates Testing Library queries with Cypress. It offers similar functionalities to @testing-library/cypress, allowing you to use Testing Library's queries within Cypress tests.

cypress-axe

cypress-axe is a plugin for Cypress that integrates the axe-core accessibility testing engine. While it focuses on accessibility testing rather than user interaction, it complements @testing-library/cypress by ensuring your application is accessible.

cypress-cucumber-preprocessor

cypress-cucumber-preprocessor allows you to write Cypress tests using the Gherkin syntax. While it doesn't provide the same querying capabilities as @testing-library/cypress, it offers a different approach to writing readable and maintainable tests.

README

cypress-testing-library

Simple and complete custom Cypress commands and utilities that encourage good testing practices.

Read the docs | Edit the docs

---

The problem

You want to use dom-testing-library methods in your Cypress tests.

This solution

This allows you to use all the useful dom-testing-library methods in your tests.

Table of Contents

• Installation
  • With typescript
• Usage
• Other Solutions
• Contributors
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

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

With typescript

Typings are defined under @testing-library/cypress/typings, and should be added as follows in tsconfig.json:

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

Usage

cypress-testing-library extends Cypress' cy command.

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

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

You can now use all of dom-testing-library's getBy, getAllBy, queryBy and queryAllBy commands. See the dom-testing-library docs for reference

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

cy.getAllByText('Jackie Chan').click()
cy.queryByText('Button Text').should('exist')
cy.queryByText('Non-existing Button Text').should('not.exist')
cy.queryByLabelText('Label text', {timeout: 7000}).should('exist')
cy.get('form').within(() => {
  cy.getByText('Button Text').should('exist')
})
cy.get('form').then(subject => {
  cy.getByText('Button Text', {container: subject}).should('exist')
})

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.

Other Solutions

I'm not aware of any, if you are please make a pull request and add it here!

Contributors

Thanks goes to these people (emoji key):

Kent C. Dodds 💻 📖 🚇 ⚠️	Ivan Babak 💻 🤔	Łukasz Gandecki 💻 ⚠️	Peter Kamps 💻 📖 🤔 ⚠️	Airat Aminev 💻 ⚠️ 🔧	Adrian Smijulj 💻	Soo Jae Hwang 🐛 💻 ⚠️
Justin Hall 💻 ⚠️	euzebe 📖	jkdowdle 💻	Brian Ng 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT