Extend Puppeteer e2e tests with UserWay accessibility analysis

UserWay CI/CD injects accessibility analysis into existing end-to-end tests through the @userway/a11y-puppeteer npm package. This library works with Puppeteer's Page instance, collects accessibility insights during e2e test executions, and saves reports in the uw-a11y-reports directory.

1. Install @userway/a11y-puppeteer package

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

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

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

2. Update Puppeteer e2e tests with setupUserway

Import and invoke the setupUserway() function in your Puppeteer's test files in order to initialize and configure accessibility analysis. It is recommended to create a setup file or a test initialization file, e.g. setupPuppeteer.ts and add setupUserway invocation into it. Then just import setupPuppeteer.ts in all of your tests.

import { setupUserway } from '@userway/a11y-puppeteer'
 
test.describe('navigation', () => {
  test.beforeAll(async () => {
    setupUserway({
      elementScreenshots: true,
      printViolationsTable: true,
      pageScreenshot: true,
      reportPath: './uw-a11y-reports',
    })
  })
})

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

3. Update your Puppeteer e2e tests with userwayAnalysis

Adding the 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 userwayAnalysis() at the end of every e2e test case.

const { userwayAnalysis } = require('@userway/a11y-puppeteer')
 
test('example test', async ({ page }) => {
  await page.goto('https://website.com')
 
  await userwayAnalysis(page)
})

Note: userwayAnalysis() accepts multiple arguments and can be parametrized in order to meet your specific conditions and requiremens. Here is more advanced usage:

userwayAnalysis(page, {
  strict: false,
  saveReport: 'json',
  elementScreenshots: true,
  reportPath: './uw-a11y-reports',
})

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

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

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

4. Optional configuration

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

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

• 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 puppeteer 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-puppeteer package refer to the documentation

Prerequisites

• @userway/a11y-puppeteer compatible with Chrome and Chromium only
• Puppeteer version 22.14.0 or higher is required
• Node.js v16.20.2 or higher