Cypress Testing Library

While based on DOM Testing Library, Cypress Testing Library has several key differences to align with Cypress behavior:

1. Element Types: It supports both jQuery elements and DOM nodes. When chaining a query, it extracts the first DOM node from the subject to use as the container for the underlying DOM Testing Library function.
2. Query Support:
   • query* is not supported. Use .should('not.exist') to assert an element is missing.
   • get* is not supported. Use find* queries which use Cypress retryability.
3. Selection Behavior:
   • find* commands will fail if more than one element is found (to maintain compatibility with other Testing Libraries).
   • findAll* commands select multiple elements, behaving more like standard Cypress commands.
4. Actions: Cypress handles actions on multiple elements by failing if more than one is found. For example, cy.findAllByText('Some Text').click() will automatically fail if the selector matches multiple elements.
5. Enforcing Single Elements: To explicitly ensure only one element exists, use:
   • cy.findAllByText('Some Text').should('have.length', 1)
   • cy.findByText('Some Text').should('exist')

To use the library, you must first import the commands in your cypress/support/commands.js file:

Cypress Testing Library extends the Cypress cy command, allowing you to use findBy and findAllBy methods. These methods leverage Cypress's built-in retryability.

Note on Query Types:

• find* queries are supported and use Cypress retryability.
• findAll* queries are supported and can select multiple elements.
• query* queries are not supported; use .should('not.exist') instead to check for absence.
• get* queries are not supported; use find* instead.

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

// Example usage:
cy.findAllByText('Button Text').should('exist')
cy.findAllByText('Non-existing Button Text').should('not.exist')
cy.findAllByLabelText('Label text', {timeout: 7000}).should('exist')
cy.findAllByText('Jackie Chan').click()

// Scoped queries:
cy.get('form').findAllByText('Button Text').should('exist')

The library automatically registers a suite of Cypress commands based on the available queries in @testing-library/dom. These commands follow the pattern of findBy*, getBy*, and queryBy* (e.g., cy.findByRole, cy.getByText, cy.queryByLabelText).

Command Usage

Commands can be used with standard Cypress chaining. They accept an optional options object as the last argument, which can include:

• timeout: The timeout for the command.
• container: A specific element to scope the search to.
• log: A boolean to enable or disable Cypress logging for this command (defaults to true).

Error Handling and Assertions

• Multiple Elements: If a command that expects a single element (like getBy* or findBy*) finds more than one element, it will throw an error: Found multiple elements with the text: <input>.
• Failure Messages: When a query fails, the error message is enhanced to include the specific selector used, making it easier to debug .should('exist') failures.
• Return Value: Commands return a Cypress-wrapped jQuery object containing the matched elements.