cypress-a11y-report

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.

Previously published as cypress-accessibility. It has been renamed to cypress-a11y-report to avoid confusion with the official Cypress Accessibility feature.

Installation

This plugin only works with Cypress version 10.0.0 or higher.

# pnpm
pnpm add cypress axe-core cypress-a11y-report -D

# npm
npm install cypress axe-core cypress-a11y-report -D

Configuration

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

import 'cypress-a11y-report';

TypeScript

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

{
  "compilerOptions": {
    "types": ["cypress", "cypress-a11y-report"]
  }
}

Cypress Commands

cy.injectAxe()

Injects axe-core® into the current window and initializes it. This command should be called before any other cypress-a11y-report 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.

Acknowledgements

This plugin is heavily based on cypress-axe. I would like to thank the maintainers and contributors of that project for their hard work.

I would also like to thank the maintainers and contributors of axe-core® for their hard work on the axe-core® library.

License

MIT