Registry / testing / cypress-axe

cypress-axe

JSON →
library1.7.0jsnpmunverified

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-axe
INSTALL
IMPORT
SIG · CYPRESS-AXE
C
cypress-axe
testingjavascriptv1.7.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cypress-axe commands
import 'cypress-axe'
import { injectAxe } from 'cypress-axe'
cypress-axe extends the Cypress `cy` object with custom commands (`cy.injectAxe`, `cy.checkA11y`, `cy.configureAxe`). It is imported for its side effects in Cypress support files (e.g., `cypress/support/e2e.js` for Cypress v10+).

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.

/* cypress/plugins/index.js or cypress.config.ts (setupNodeEvents) */ // For Cypress v10+ in cypress.config.ts import { defineConfig } from 'cypress'; export default defineConfig({ e2e: { setupNodeEvents(on, config) { on('task', { log(message) { console.log(message); return null; }, table(message) { console.table(message); return null; } }); } } }); // For older Cypress versions in cypress/plugins/index.js // module.exports = (on, config) => { // on('task', { // log(message) { // console.log(message); // return null; // }, // table(message) { // console.table(message); // return null; // } // }); // }; /* cypress/support/e2e.ts (for Cypress v10+) or cypress/support/index.ts (for v9-) */ import 'cypress-axe'; /* cypress/tsconfig.json */ // Add "cypress-axe" to types array // { // "compilerOptions": { // "types": ["cypress", "node", "cypress-axe"] // } // } /* cypress/e2e/accessibility.cy.ts */ describe('Accessibility tests', () => { beforeEach(() => { cy.visit('http://localhost:3000'); // Replace with your application's URL cy.injectAxe(); }); it('Should have no detectable accessibility violations on load', () => { cy.checkA11y(); }); it('Should have no detectable accessibility violations after user interaction', () => { cy.get('button#open-modal').click(); // Example user interaction cy.checkA11y(); // Check again after interaction }); });
Debug
Known issues
breakingUpgrading to Cypress v10 and above requires `cypress-axe` v1.0.0 or higher. This involves changes to Cypress's file structure (e.g., `cypress/support/index.js` becomes `cypress/support/e2e.js`) and potentially how plugins are configured (`cypress.config.ts` vs `cypress/plugins/index.js`).
fix
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.
affects: >=1.0.0
gotchaFor Cypress v9 and below, you must use an older version of `cypress-axe` (e.g., `0.14.0`). Installing the latest `cypress-axe` with an older Cypress version will result in peer dependency conflicts and potential runtime errors.
fix
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`.
affects: <1.0.0
gotchaThe `cy.injectAxe()` command must be called after `cy.visit()` within your test or `beforeEach` hook. Calling it before `cy.visit()` will not inject `axe-core` into the application's iframe context.
fix
Always ensure `cy.injectAxe()` is invoked only after the page has been loaded with `cy.visit()`.
affects: >=0.1.0
gotchaAccessibility violations found by `axe-core` are logged as console errors by default within the browser. To see a structured report and summary in your terminal, you must configure a Cypress `task` to capture and log these messages.
fix
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))`.
affects: >=0.1.0
Errors
Common errors & fixes
cy.injectAxe is not a function
The `cypress-axe` commands have not been correctly loaded into Cypress.
fix
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.
Cannot find module 'axe-core/axe.min.js'
The `axe-core` peer dependency is either not installed or `cypress-axe` cannot resolve its path.
fix
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') })`.
Property 'injectAxe' does not exist on type 'Chainable<JQuery<HTMLElement>>'
TypeScript compiler is unaware of the custom Cypress commands added by `cypress-axe`.
fix
Add `"cypress-axe"` to the `types` array in your Cypress `tsconfig.json` file, usually alongside `"cypress"` and `"node"`: `"types": ["cypress", "node", "cypress-axe"]`.
Upgrade
Version history
1.7.0latest on npm
Audit
Dependencies
axe-corerequiredCore library for accessibility rule definitions and checks.
cypressrequiredTest runner framework that cypress-axe extends with custom commands.
Agent activity
5 hits · last 30 days
node
4
Resources
cypress-axe — npm install cypress-axe · libregistry