---
title: Accessibility Testing with Cypress and cypress-axe
description: Check pages for WCAG A and AA violations with cypress-axe and axe-core
  in your Cypress tests, running on TestingBot's cloud browsers with the TestingBot
  Cypress CLI.
source_url:
  html: https://testingbot.com/support/accessibility/web/cypress
  md: https://testingbot.com/support/accessibility/web/cypress.md
---

# Cypress and cypress-axe

[cypress-axe](https://github.com/component-driven/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](https://testingbot.com/support/web-automate/cypress).

## Installation

cypress-axe needs `axe-core` next to it:

```bash
npm i -D cypress-axe axe-core
```

Then register the commands in your support file, `cypress/support/e2e.js`:

```javascript
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:

```javascript
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](https://testingbot.com/support/accessibility/web/manual-checks).

## Run on TestingBot

Set up the [TestingBot Cypress CLI](https://testingbot.com/support/web-automate/cypress) 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:

```json
{
    "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:

```console
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 `true` as the fourth argument logs violations without failing the test, which helps while you work through an existing backlog.
- Any other option, such as `runOnly` or `rules`, is passed on to `axe.run`.

## Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)
