The @dom-assertions/cypress-dom package provides custom assertions to make your Cypress tests more declarative, readable, and maintainable.

Installation

First, install the @dom-assertions/cypress-dom package.

npm install --save-dev @dom-assertions/cypress-dom

yarn add --dev @dom-assertions/cypress-dom

pnpm add --save-dev @dom-assertions/cypress-dom

Then, import it into cypress/support/commands.ts

import '@dom-assertions/cypress-dom'

Note: We recommend using Cypress Testing Library with this library for writing more readable and accessibility-driven tests.

Assertions

be.invalid

Asserts that the given element is invalid.

Example

<div>
  <label for="username">Username</label>
  <input id="username" type="text" aria-invalid="true" />
</div>

cy.findByLabelText('Username').should('be.invalid')

be.required

Asserts that the given element is required.

Example

<div>
  <label for="username">Username</label>
  <input id="username" type="text" required />
</div>

cy.findByLabelText('Username').should('be.required')

be.valid

Asserts that the given element is valid.

Example

<div>
  <label for="username">Username</label>
  <input id="username" type="text" />
</div>

cy.findByLabelText('Username').should('be.valid')

have.description

Asserts that the given element has the expected accessible description.

Example

<button aria-describedby="trash-desc">Move to trash</button>
<p id="trash-desc">
  Items in the trash will be permanently removed after 30 days.
</p>

cy.findByRole('button', { name: 'Move to trash' }).should('have.description')
cy.findByRole('button', { name: 'Move to trash' }).should(
  'have.description',
  'Items in the trash will be permanently removed after 30 days.',
)

have.errorMessage

Asserts that the given element has the expected ARIA error message. Please note that the element should indicate an error state using aria-invalid set to true.

Example

<label for="email">Email</label>
<input
  type="email"
  name="email"
  id="email"
  aria-invalid="true"
  aria-errormessage="error-message"
/>
<span id="error-message">Enter a valid email address</span>

cy.findByLabelText('Email').should('have.errorMessage')
cy.findByLabelText('Email').should(
  'have.errorMessage',
  'Enter a valid email address',
)

have.name

Asserts that the given element has the expected accessible name.

Example

<span
  role="checkbox"
  aria-checked="false"
  tabindex="0"
  aria-labelledby="label"
/>
<span id="label">I agree to the Terms and Conditions.</span>

cy.findByRole('checkbox').should('have.name')
cy.findByRole('checkbox').should(
  'have.name',
  'I agree to the Terms and Conditions.',
)