Cypress-axe integrates the popular axe-core library into Cypress, enabling automated web accessibility testing directly within end-to-end test suites. This package allows developers to scan their application for WCAG violations and other accessibility issues at various points in their user flows, not just on initial page load. The current stable version is 1.7.0, which supports Cypress up to v15 and axe-core v3 or v4. Releases are generally aligned with new Cypress major versions, ensuring compatibility and continuous support for the latest testing environments. Its key differentiator is the seamless ability to run accessibility checks dynamically after user interactions, leveraging axe-core's comprehensive ruleset to provide detailed, actionable feedback directly within the Cypress test runner environment, making accessibility a part of the standard testing workflow.
npm install cypress-axeVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates setting up `cypress-axe` to run basic accessibility checks on page load and after a user interaction within a Cypress test suite. It includes the necessary installations, Cypress configuration for logging, support file import, TypeScript type setup, and example test code.
Ensure `cypress-axe` is updated to a compatible version for your Cypress setup. For Cypress v10+, update your `cypress/support/e2e.js` (or `.ts`) file to include `import 'cypress-axe'` and configure `setupNodeEvents` in `cypress.config.ts` for tasks.
Check the `peerDependencies` section of `cypress-axe` on npm and install the version compatible with your Cypress installation. For Cypress v9, use `npm install --save-dev cypress-axe@0.14.0`.
Always ensure `cy.injectAxe()` is invoked only after the page has been loaded with `cy.visit()`.
Add a `log` or `table` task to your Cypress `plugins/index.js` (for v9-) or `cypress.config.ts`'s `setupNodeEvents` (for v10+) function, then pass the `violations` array to `cy.checkA11y(null, null, (violations) => cy.task('table', violations))`.Ensure that `import 'cypress-axe'` is present in your Cypress support file (e.g., `cypress/support/e2e.js` for Cypress v10+ or `cypress/support/index.js` for older versions) and that the file is included in your Cypress configuration.
Install `axe-core` as a dev dependency: `npm install --save-dev axe-core`. If issues persist, consider using the `axeCorePath` option in `cy.injectAxe` to specify the exact path, e.g., `cy.injectAxe({ axeCorePath: require.resolve('axe-core/axe.min.js') })`.Add `"cypress-axe"` to the `types` array in your Cypress `tsconfig.json` file, usually alongside `"cypress"` and `"node"`: `"types": ["cypress", "node", "cypress-axe"]`.