Cypress and cypress-axe
cypress-axe is an open-source plugin that adds two Cypress commands: cy.injectAxe() loads the axe-core accessibility engine into the page under test, and cy.checkA11y() runs it and fails the test when it finds violations.
The scan runs inside your Cypress test, with the axe-core version installed in your project. You can run those tests on TestingBot's browsers with the TestingBot Cypress CLI.
Installation
cypress-axe needs axe-core next to it:
npm i -D cypress-axe axe-core
Then register the commands in your support file, cypress/support/e2e.js:
import 'cypress-axe'
Example test
Inject axe-core after every cy.visit(), then check the page. This example runs the WCAG 2.0 and 2.1 level A and AA rules:
describe('Accessibility', () => {
it('home page has no automated WCAG A/AA violations', () => {
cy.visit('https://example.com/')
cy.injectAxe()
cy.checkA11y(null, {
runOnly: {
type: 'tag',
values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']
}
})
})
})
cy.injectAxe() has to run again after each cy.visit(), because a new page load removes axe-core from the page.
To check a dialog or menu, open it with Cypress first and call cy.checkA11y() again.
A passing check means axe-core found no violations of the rules it ran on that page state. It does not mean the page is accessible: see what automated checks don't catch.
Run on TestingBot
Set up the TestingBot Cypress CLI as usual.
The CLI uploads your Cypress project and the TestingBot machine installs the packages you list under run_settings.npm_dependencies in testingbot.json, so add cypress-axe and axe-core there:
{
"run_settings": {
"cypress_project_dir": "./",
"npm_dependencies": {
"cypress-axe": "^1.7.0",
"axe-core": "^4.11.0"
}
}
}
Use the same versions you have in your own package.json, then start the run:
testingbot-cypress run
Options
-
cy.checkA11y('main')checks only part of the page. The first argument also accepts{ include: [...], exclude: [...] }. -
includedImpacts: ['serious', 'critical']in the options fails the test only for those impact levels. - Passing
trueas the fourth argument logs violations without failing the test, which helps while you work through an existing backlog. - Any other option, such as
runOnlyorrules, is passed on toaxe.run.