cypress-axe-core

Test accessibility with axe-core in Cypress.

⚠️ UPDATE: cypress-axe now supports Cypress 8 (latest release). So you should consider using/switching to the orignal package.

Forked from cypress-axe ⑂

Reasons:

• to upgrade dependencies (i.e. Cypress ^7 & axe-core ^4)
• RFC 75 👀

1. Installation and Setup
   • Typescript
2. Examples
   • Simple
   • Customised
3. Commands
   • cy.injectAxe
   • cy.checkA11y
   • cy.configureCypressAxe
   • cy.configureAxe

Installation and Setup

1. Install required packages. Assuming you have Cypress installed already, you will only need to:

npm install --save-dev axe-core cypress-axe-core

2. Include the commands by importing cypress-axe-core in cypress/support/index.js file:

import 'cypress-axe-core'

3. Enable results logging by defining cy.tasks in cypress/plugins/index.js file:

module.exports = (on, config) => {
  on('task', {
    log(message) {
      console.log(message)
      return null
    },

    table(message) {
      console.table(message)
      return null
    }
  })
}

NOTE: You can control how results are displayed via the violationsCb config option

After following the steps above (and defining cy.tasks), violations will be displayed as follows:

• Cypress

• Terminal

• Browser

TypeScript

If you’re using TypeScript, add cypress-axe-core types to your Cypress’s tsconfig.json file:

{
  "compilerOptions": {
    "baseUrl": "./",
    "target": "es5",
    "lib": ["esnext", "dom"],
    "types": ["cypress", "cypress-axe-core"]
  },
  "include": ["."]
}

Examples

Simple

it('passes axe', () => {
  cy.visit('/')
  cy.injectAxe()
  // ...

  cy.checkA11y() // checks the whole document

  cy.get('#mobile-menu').checkA11y() // checks id="mobile-menu only

  cy.wrap({ exclude: ['.not-me'] }).checkA11y() // checks the whole document except class=".not-me"
})

Customised

Leveraging Cypress commands, you can create your own custom command that calls cy.checkA11y with the config you want. For example, if you only want to assert against serious & critical violations but ignore color-contrast rule, you can do something like this:

// cypress/support/commands.js
Cypress.Commands.add(
  'checkAxeViolations',
  { prevSubject: 'optional' },
  (context, options, label) => {
    cy.wrap(context).checkA11y(
      {
        shouldFailFn: violations =>
          violations.filter(
            v =>
              v.id !== 'color-contrast' &&
              ['serious', 'critical'].includes(v.impact)
          ),
        ...options
      },
      label
    )
  }
)

// some.spec.js
it('passes custom axe tests', () => {
  cy.visit('/')
  cy.injectAxe()
  // ...
  cy.checkAxeViolations() // 👈
})

Commands

cy.injectAxe

This will inject the axe-core runtime into the page under test. You must run this after a call to cy.visit() and before you run the checkA11y command.

You run this command with cy.injectAxe() either in your test, or in a beforeEach, as long as the visit comes first.

beforeEach(() => {
  cy.visit('http://localhost:9000')
  cy.injectAxe()
})

cy.checkA11y

When not chained to another element, it will run against the whole document. You can have it at the end of your test (after other interaction assertions) so it checks against all possible violations. It accepts the same (optional) config object that cy.configureCypressAxe accepts

Note: if you have a toggle-able element i.e. a side menu, make sure it's on (shown) by the time cy.checkA11y is called, otherwise you might end up with some false-positive cases. Or, you can target those elements directly to make sure they're tested

cy.get('#menu-button').click()
cy.get('#side-menu-container').checkA11y()

cy.configureCypressAxe

Instead of wrapping or overwriting cy.checkA11y, you can configure it. It accepts the following:

• axeOptions passed to axe-core.
• shouldFailFn function that returns array of violations to check for.
• skipFailures if true, it will log the violations but not assert against them.
• violationsCb reporter function that receives the result.

The default violationsCb function assumes that cy.task('log') and cy.task('table') have been defined already during the Installation & setup. If you don't want to define those tasks, you can pass a function here to control how results are outputted.

cy.configureCypressAxe({
  axeOptions: [], // axe.RunOptions[]
  shouldFailFn: violations => violations,
  skipFailures: false,
  violationsCb: ({
    filename: 'test.spec.ts', // spec filename
    results: [], // violations axe.Result[]
    label: 'my custom component', // if passed to checkA11y
  }) => void,
})

cy.configureAxe

To configure the format of the data used by aXe. This can be used to add new rules, which must be registered with the library to execute.

Description

User specifies the format of the JSON structure passed to the callback of axe.run

Link - aXe Docs: axe.configure

it('Has no detectable a11y violations on load (custom configuration)', () => {
  // Configure aXe and test the page at initial load
  cy.configureAxe({
    branding: {
      brand: String,
      application: String
    },
    reporter: 'option',
    checks: [Object],
    rules: [Object],
    locale: Object
  })
  cy.checkA11y()
})

Authors

The project was created by Andy Van Slaars, and maintained by Artem Sapegin.

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT License, see the included License.md file.