cypress-axe-core
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    cypress-axe-core

    npm Node.js CI status

    Test accessibility with axe-core in Cypress.

    Forked from cypress-axe

    Reasons:

    • to upgrade dependencies (i.e. Cypress ^7 & axe-core ^4)
    • RFC 75 👀
    1. Installation and Setup
    2. Examples
    3. Commands

    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
    1. Include the commands by importing cypress-axe-core in cypress/support/index.js file:
    import 'cypress-axe-core'
    1. 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 Default Cypress output

    • Terminal Default terminal output

    • Browser Default browser console output

    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):


    Samuel Custer

    💻 📖

    Michael Toth

    💻

    Nicholas Boll

    💻

    Mike Davis

    💻

    chit786

    💻 📖

    Adrien courdavault

    💻

    Brett Zamir

    💻

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

    License

    MIT License, see the included License.md file.

    Install

    npm i cypress-axe-core

    DownloadsWeekly Downloads

    3,857

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    20.7 kB

    Total Files

    15

    Last publish

    Collaborators

    • mcha