cypress-axe

What is cypress-axe?

The cypress-axe npm package is a plugin for Cypress that integrates the axe-core accessibility testing engine. It allows you to automate accessibility testing within your Cypress end-to-end tests, making it easier to identify and fix accessibility issues in your web applications.

What are cypress-axe's main functionalities?

Injecting axe-core

This feature allows you to inject the axe-core library into your application. This is a necessary step before running any accessibility checks.

cy.injectAxe();

Running accessibility checks

This feature allows you to run accessibility checks on the entire page or a specific element. It will log any accessibility violations to the Cypress test runner.

cy.checkA11y();

Customizing axe-core options

This feature allows you to customize the axe-core options, such as specifying which accessibility standards to test against. In this example, it runs checks only for WCAG 2.0 A and AA standards.

cy.checkA11y(null, { runOnly: ['wcag2a', 'wcag2aa'] });

Excluding elements from checks

This feature allows you to exclude specific elements from accessibility checks. In this example, elements with the class 'ignore-this' will be excluded from the checks.

cy.checkA11y({ exclude: ['.ignore-this'] });

Other packages similar to cypress-axe

axe-core

axe-core is the underlying library used by cypress-axe for accessibility testing. It can be used directly in JavaScript applications to perform accessibility checks. While cypress-axe integrates axe-core with Cypress, axe-core itself can be used in various environments, including Node.js and browser extensions.

pa11y

pa11y is an automated accessibility testing tool that runs accessibility tests on web pages and reports issues. It can be used as a command-line tool or integrated into CI/CD pipelines. Unlike cypress-axe, which is specifically designed for use with Cypress, pa11y is a standalone tool that can be used independently.

jest-axe

jest-axe is a custom matcher for Jest that uses axe-core to perform accessibility checks in Jest tests. It allows you to write accessibility tests alongside your unit tests. While cypress-axe is designed for end-to-end testing with Cypress, jest-axe is intended for unit testing with Jest.

README

cypress-axe

This package provides two simple Cypress commands to help test your applications for accessibility issues using axe-core.

Install and configure

• Add as a dev dependency of your project with: npm i -D cypress-axe
• Include the commands in your Cypress specs by adding import 'cypress-axe' to the Cypress > Support > index.js file.

Commands

injectAxe

This will inject the axe-core runtime into the page under test. You must run this after a call to cy.visit() and before you run the checkA11y command.

You run this command with cy.injectAxe() either in your test, or in a beforeEach, as long as the visit comes first.

beforeEach(() => {
  cy.visit('http://localhost:9000')
  cy.injectAxe()
})

checkA11y

This will run axe against the document at the point in which it is called. This means you can call this after interacting with your page and uncover accessibility issues introduced as a result of rendering in response to user actions.

it('Has no detectable a11y violations on load', () => {
  // Test the page at initial load
  cy.checkA11y()
})

it('Has no a11y violations after button click', () => {
  // Interact with the page, then check for a11y issues
  cy.get('button').click()
  cy.checkA11y()
})

Output

When accessibility violations are detected, your test will fail and an entry titled "A11Y ERROR!" will be added to the command log for each type of violation found (they will be above the failed assertion). Clicking on those will reveal more specifics about the error in the DevTools console.