E2E test frameworksWebdriverIOGetting started

Intro

Extend WebdriverIO e2e tests with UserWay accessibility analysis

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

@userway/a11y-webdriverio can be ran with wdio or in a standalone mode, just pass browser object to userwayAnalysis function.

Prerequisites

  • WebdriverIO version 8.24.12 or higher is required

  • Node.js v18.20.4 or higher

Installation

Install @userway/a11y-webdriverio package

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

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

Update WebdriverIO e2e tests with setupUserway

Import and invoke the setupUserway() function in your WebdriverIO’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. setupWebdriverIO.ts and add setupUserway invocation into it. Then just import setupWebdriverIO.ts in all of your tests.

import { setupUserway } from '@userway/a11y-webdriverio'
 
setupUserway({
  screenshots: false,
  printViolationsTable: true,
  ignoreUrls: ['http://localhost:5000'],
})

Update WebdriverIO 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.

describe('test', () => {
  it('should pass userwayAnalysis', async () => {
    await browser.url('http://localhost:5000', {})
    await userwayAnalysis(browser, {})
  })
})

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

await userwayAnalysis(browser, {
  strict: false,
  screenshots: true,
  savePageOrigin: true,
})

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

To see more examples of @userway/a11y-webdriverio package usage visit sample project repository userway/sample-test-project

Optional configuration

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

{
  'compilerOptions': {
    'types': ['webdriverio', '@userway/a11y-webdriverio']
  }
}

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

# .gitignore
uw-a11y-reports

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 WebdriverIO 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 userwayAnalysis invocations in your e2e tests. Example of a expected report file name uw-a11y-report-lvoeobzh.json
APIUsage