cypress-a11y-report

!MIT
!CI

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

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

``bash


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:

`ts
import 'cypress-a11y-report';
`

$3

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

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

Cypress Commands

$3

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

`ts
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. |

$3

Configures axe-core® with the given options.

`ts
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.

$3

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

`ts
// 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