{"id":13037,"library":"cypress-axe","title":"Cypress-axe: Accessibility Testing with axe-core","description":"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.","status":"active","version":"1.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/component-driven/cypress-axe","tags":["javascript","a11y","accessibility","axe","axe-core","cypress","typescript"],"install":[{"cmd":"npm install cypress-axe","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-axe","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-axe","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for accessibility rule definitions and checks.","package":"axe-core","optional":false},{"reason":"Test runner framework that cypress-axe extends with custom commands.","package":"cypress","optional":false}],"imports":[{"note":"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+).","wrong":"import { injectAxe } from 'cypress-axe'","symbol":"Cypress-axe commands","correct":"import 'cypress-axe'"}],"quickstart":{"code":"/* cypress/plugins/index.js or cypress.config.ts (setupNodeEvents) */\n// For Cypress v10+ in cypress.config.ts\nimport { defineConfig } from 'cypress';\n\nexport default defineConfig({\n  e2e: {\n    setupNodeEvents(on, config) {\n      on('task', {\n        log(message) {\n          console.log(message);\n          return null;\n        },\n        table(message) {\n          console.table(message);\n          return null;\n        }\n      });\n    }\n  }\n});\n\n// For older Cypress versions in cypress/plugins/index.js\n// module.exports = (on, config) => {\n//   on('task', {\n//     log(message) {\n//       console.log(message);\n//       return null;\n//     },\n//     table(message) {\n//       console.table(message);\n//       return null;\n//     }\n//   });\n// };\n\n\n/* cypress/support/e2e.ts (for Cypress v10+) or cypress/support/index.ts (for v9-) */\nimport 'cypress-axe';\n\n/* cypress/tsconfig.json */\n// Add \"cypress-axe\" to types array\n// {\n//   \"compilerOptions\": {\n//     \"types\": [\"cypress\", \"node\", \"cypress-axe\"]\n//   }\n// }\n\n/* cypress/e2e/accessibility.cy.ts */\ndescribe('Accessibility tests', () => {\n  beforeEach(() => {\n    cy.visit('http://localhost:3000'); // Replace with your application's URL\n    cy.injectAxe();\n  });\n\n  it('Should have no detectable accessibility violations on load', () => {\n    cy.checkA11y();\n  });\n\n  it('Should have no detectable accessibility violations after user interaction', () => {\n    cy.get('button#open-modal').click(); // Example user interaction\n    cy.checkA11y(); // Check again after interaction\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Upgrading 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`).","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Always ensure `cy.injectAxe()` is invoked only after the page has been loaded with `cy.visit()`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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))`.","message":"Accessibility 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `cypress-axe` commands have not been correctly loaded into Cypress.","error":"cy.injectAxe is not a function"},{"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') })`.","cause":"The `axe-core` peer dependency is either not installed or `cypress-axe` cannot resolve its path.","error":"Cannot find module 'axe-core/axe.min.js'"},{"fix":"Add `\"cypress-axe\"` to the `types` array in your Cypress `tsconfig.json` file, usually alongside `\"cypress\"` and `\"node\"`: `\"types\": [\"cypress\", \"node\", \"cypress-axe\"]`.","cause":"TypeScript compiler is unaware of the custom Cypress commands added by `cypress-axe`.","error":"Property 'injectAxe' does not exist on type 'Chainable<JQuery<HTMLElement>>'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}