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