Cypress-accessibility NPM

cypress-accessibility

NPM

Yet another Cypress plugin for accessibility testing powered by axe-core®. This is a fork of cypress-axe with some api changes and improvements.

Axe-core® is a trademark of Deque Systems, Inc. in the US and other countries. This plugin is not affiliated with or endorsed by Deque Systems, Inc.

If you're looking to migrate from cypress-axe, you can find the migration guide here.

Installation

This plugin only works with Cypress version 10.0.0 or higher.

# pnpm
pnpm add cypress axe-core cypress-accessibility -D

# npm
npm install cypress axe-core cypress-accessibility -D

Configuration

Add the following to your cypress/support/e2e.ts file:

import 'cypress-accessibility';

TypeScript

If you are using TypeScript, you need to add the following to your tsconfig.json file:

{
  "compilerOptions": {
    "types": ["cypress", "cypress-accessibility"]
  }
}

Cypress Commands

`cy.injectAxe()`

Injects axe-core® into the current window and initializes it. This command should be called before any other cypress-accessibility commands.

cy.injectAxe();

// or
cy.injectAxe({
  path: 'custom-path/axe-core/axe.min.js',
});

Options

Name	Type	Default	Description
`path`	`string`	`'node_modules/axe-core/axe.min.js'`	The path to the axe-core® script.

`cy.configureAxe()`

Configures axe-core® with the given options.

cy.configureAxe({
  rules: [{ id: 'color-contrast', enabled: false }],
});

Options

This accepts the same options as the axe.configure() method. You can find the full list of options here.

`cy.checkAccessibility()`

Runs axe-core® against the current document or a given element.

// Check the entire document
cy.checkAccessibility();

// Check a specific element
cy.get('button').checkAccessibility();

// Check the entire document with options
cy.checkAccessibility({
  shouldFail: (violations) => violations.length > 0,
  runOptions: {
    rules: {
      'color-contrast': { enabled: false },
    },
  },
  reporters: [(results) => console.table(results.violations)],
});

// Check a specific element with options
cy.get('button').checkAccessibility({
  shouldFail: (violations) => violations.length > 0,
  runOptions: {
    rules: {
      'color-contrast': { enabled: false },
    },
  },
  reporters: [(results) => console.table(results.violations)],
});

Options

Name	Type	Default	Description
`shouldFail`	`(violations: axe.Result) => boolean`	`(violations) => violations.length > 0`	A function that determines if the test should fail based on the violations.
`runOptions`	`axe.RunOptions`	`{}`	The options to pass to the `axe.run()` method.
`reporters`	`((results: AxeResults) => void)[]`	`[]`	An array of functions that will be called with the results.
`retry`	`{ interval: number, times: number }`	`{ interval: 500, times: 0 }`	The interval and number of times to retry the check if it fails.