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 three simple Cypress commands to help test your applications for accessibility issues using axe-core.

Install and configure

Add as a dev dependency:

npm i -D cypress-axe

Install peer dependencies:

npm i -D cypress

NOTE: axe-core is now bundled and doesn't need to be installed as a peer dependency

Include the commands

Update Cypress/support/index.js file to include the cypress-axe commands by adding:

import 'cypress-axe'

Add a task to log the messages to the terminal when the cypress executes the spec files

Example - configuring log task

Commands

cy.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()
})

cy.configureAxe

Purpose

To configure the format of the data used by aXe. This can be used to add new rules, which must be registered with the library to execute.

Description

User specifies the format of the JSON structure passed to the callback of axe.run

Link - aXe Docs: axe.configure

it('Has no detectable a11y violations on load (custom configuration)', () => {
  // Configure aXe and test the page at initial load
  cy.configureAxe({
    branding: {
      brand: String,
      application: String
    },
    reporter: 'option',
    checks: [Object],
    rules: [Object],
    locale: Object
  })
  cy.checkA11y()
})

cy.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.

Parameters on cy.checkA11y (axe.run)

context: (optional) Defines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.

options: (optional) Set of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.

Link - aXe Docs: axe.run Parameters

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

it('Has no detectable a11y violations on load (with custom parameters)', () => {
  // Test the page at initial load (with context and options)
  cy.checkA11y('.example-class', {
    runOnly: {
      type: 'tag',
      values: ['wcag2a']
    }
  })
})

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

Optionally you can also pass additional argument skipFailures to disable the failures and only log them to the console output

Reference : https://github.com/avanslaars/cypress-axe/issues/17

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.

Contributors

Thanks goes to these wonderful people (emoji key):

Samuel Custer 💻 📖

Michael Toth 💻

Nicholas Boll 💻

Mike Davis 💻

chit786 💻 📖

Adrien courdavault 💻

Brett Zamir 💻

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