Extend Cypress e2e tests with UserWay accessibility analysis

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

1. Install @userway/a11y-cypress package

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

npm install --save-dev @userway/a11y-cypress

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

2. Update Cypress support file with setupUserway

Import and invoke the setupUserway() 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 { setupUserway } from '@userway/a11y-cypress'
 
setupUserway({
  strict: false,
  saveReport: true,
  reportPath: './uw-a11y-reports',
})

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

3. Update Cypress e2e tests with userwayAnalysis

Adding the cy.userwayAnalysis() 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 uw-a11y-reports directory. As a rule of thumb, you should invoke cy.userwayAnalysis() at the end of every e2e test case.

cy.userwayAnalysis()

Note: cy.userwayAnalysis() 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.userwayAnalysis({
    strict: false,
    screenshots: true,
  })
})

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

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

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

4. Optional configuration

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

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

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

uw-a11y-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 uw-a11y-reports/reports for JSON files. Number of report files should be equal to number of cy.userwayAnalysis invocations in your e2e tests. Example of a expected report file name uw-a11y-report-lvoeobzh.json

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

6. Prerequisites

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