Getting Started

Intro

Extend your WebdriverIO e2e tests with Level CI accessibility analysis.

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

@level-ci/a11y-webdriverio can be run with wdio or in standalone mode — just pass the browser object to the levelAnalyze function.

Prerequisites

WebdriverIO version 8.24.12 or higher
Node.js version 18.20.4 or higher

Installation

Install the Level CI WebdriverIO package in your project:


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

Setup

Initialize Level CI

Import and invoke the setupLevel() function in your WebdriverIO test files to configure accessibility analysis.
It’s recommended to create a setup file (e.g., setupWebdriverIO.ts) and import it into all tests:


import { setupLevel } from '@level-ci/a11y-webdriverio'
 
setupLevel({
  ignoreUrls: ['http://localhost:5000'],
})

Add `levelAnalyze` to Tests

Adding the levelAnalyze function to your e2e tests allows you to perform static page analysis at any point.
With each invocation, a report of accessibility violations will be saved in level-ci-reports.

Example:


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

Advanced Usage

levelAnalyze accepts configuration options to meet your project’s specific needs:


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

Every levelAnalyze invocation counts toward consuming project Self-Hosted scans.

Optional Configuration

TypeScript Support

If using TypeScript, add @level-ci/a11y-webdriverio to the types section in your tsconfig.json:


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

Git Ignore

Ignore generated reports by adding the folder to .gitignore:


# .gitignore
level-ci-reports

Verify Configuration

To validate your setup before committing:

Make all necessary setup changes as described above
Run your e2e tests locally
Ensure tests pass without errors
Check the level-ci-reports/reports directory for JSON report files
- The number of report files should match the number of levelAnalyze() invocations
- Example report file: level-ci-report-abc123.json

Getting started