Extend Cypress e2e tests with Level CI accessibility analysis

Level CI injects accessibility analysis into existing end-to-end tests through the @level-ci/a11y-cypress npm package. This library extends Cypress’s cy commands, collects accessibility insights during e2e test executions, and saves reports in the level-ci-reports directory.

1. Install @level-ci/a11y-cypress package

Install the @level-ci/a11y-cypress package in the root of your Cypress e2e testing project.

npm install --save-dev @level-ci/a11y-cypress

For more information about installation of @level-ci/a11y-cypress package refer to the documentation

2. Update Cypress support file with levelSetup

Import and invoke the levelSetup() function in your Cypress’s support file (usually cypress/support/e2e.js or cypress/support/e2e.ts) in order to initialize and configure accessibility analysis.

import { levelSetup } from '@level-ci/a11y-cypress'
 
levelSetup({
  reportPath: './level-ci-reports',
})

For more information about configuration of @level-ci/a11y-cypress package refer to the documentation

3. Update Cypress e2e tests with levelAnalyze

Adding the cy.levelAnalyze() function call to your existing end-to-end tests allows you to perform static page analysis at any point during test execution. With each function invocation, a report of accessibility violations will be saved in the level-ci-reports directory. As a rule of thumb, you should invoke cy.levelAnalyze() at the end of every e2e test case.

cy.levelAnalyze()

Note: cy.levelAnalyze() accepts an argument and can be parametrized in order to meet your specific conditions and requirements. Here is more advanced usage:

it('basic example', () => {
  cy.visit('some example website')
 
  cy.levelAnalyze({
    elementScreenshots: true,
  })
})

For more information about levelAnalyze() configuration options visit cypress API doc

Note: Every cy.levelAnalyze() function invocation counts towards consuming project Self-Hosted scans.

To see more examples of @level-ci/a11y-cypress package usage visit one of our sample projects

4. Optional configuration

• Update tsconfig.json. If you use TypeScript, add @level-ci/a11y-cypress to the types section in your tsconfig.json.

{
  "compilerOptions": {
    "types": ["cypress", "@level-ci/a11y-cypress"]
  }
}

• Update .gitignore. Ignore reports generated by the levelAnalyze function in your git commits by adding the report directory to the .gitignore file.

level-ci-reports

5. Verify configuration

It is always a good idea to validate changes made in the steps above before committing them into repository. In order to verify if your cypress configuration is correct - there are are few steps which can be performed on local developer environment:

• Make all necessary changes described above
• Run your e2e tests locally
• Make sure there is no error and tests pass successfully
• Check directory level-ci-reports/reports for JSON files. Number of report files should be equal to number of cy.levelAnalyze invocations in your e2e tests. Example of a expected report file name level-ci-report-lvoeobzh.json

For more information about troubleshooting of @level-ci/a11y-cypress package refer to the troubleshooting section of the documentation.

6. Prerequisites

• @level-ci/a11y-cypress compatible with Chrome and Chromium only
• Cypress version 10.0.0 or higher
• Node.js v16.20.2 or higher