Getting Started

The @level-ci/a11y-webdriverio package enables accessibility testing in your WebdriverIO workflow.
It lets you run static page analysis and generate detailed reports of accessibility violations based on WCAG guidelines and ACT rules.


// webdriverio/e2e/accessibility.spec.ts
import { levelAnalyze } from '@level-ci/a11y-webdriverio'
 
describe('example test', () => {
  it('runs accessibility analysis', async () => {
    await browser.url('http://localhost:5000')
    await levelAnalyze(browser)
  })
})

Prerequisites

WebdriverIO version 8.24.12 or higher

Installation

Configure .npmrc and Install @level-ci/a11y-webdriverio package

Run the following commands in the root of your project to configure the registry and authentication.


npm config --location project set @level-ci:registry https://npm.levelaccess.net/level-ci/
npm config --location project set //npm.levelaccess.net/level-ci/:_authToken=\${CLOUDSMITH_TOKEN}

Declare a Cloudsmith Token


export CLOUDSMITH_TOKEN=MY_CLOUDSMITH_TOKEN

By using the CLOUDSMITH_TOKEN you will be able to install the needed package.

Install the package.

You can do this by using either npm or yarn.


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


yarn add -D @level-ci/a11y-webdriverio

This will add @level-ci/a11y-webdriverio to the dev dependencies in package.json.

Setup

Level CI WebdriverIO is an external package that must be imported in your WebdriverIO tests.

Option 1: Call levelAnalyze function right away

Import @level-ci/a11y-webdriverio and call the levelAnalyze function:


// webdriverio/e2e/accessibility.spec.ts
import { levelAnalyze } from '@level-ci/a11y-webdriverio'
 
describe('accessibility example', () => {
  it('runs Level CI analysis', async () => {
    await browser.url('https://example.com')
 
    // Run static accessibility analysis
    await levelAnalyze(browser)
  })
})

Option 2: Using levelSetup with before in your WebdriverIO configuration

Set up levelSetup in the before hook of your wdio.conf.ts configuration file. This ensures global setup before each test, as recommended by WebdriverIO’s configuration docs :


// wdio.conf.ts
import { levelSetup } from '@level-ci/a11y-webdriverio'
 
export const config = {
  // ...other WebdriverIO config options,
 
  before: () => {
    levelSetup({
      reportPath: 'level-ci-reports-custom',
      stableSelectorAttributes: ['data-testid'],
    })
  },
}

Then use levelAnalyze in your tests:


// webdriverio/e2e/demo.spec.ts
import { levelAnalyze } from '@level-ci/a11y-webdriverio'
 
describe('test', () => {
  it('runs Level CI analysis on the home page', async () => {
    await browser.url('/')
 
    const config = {}
    await levelAnalyze(browser, config)
  })
})

Note: For more details see levelSetup usage.

Running levelAnalyze will create a report folder, where all of the issues data will be contained. File structure for the directory enables issue deduplication, which helps in achieving faster scans.

TypeScript Support

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


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

If you are not using TypeScript, you can still enable autocompletion by adding type references at the top of your test files:


/// <reference types="webdriverio" />
 
/// <reference types="@level-ci/a11y-webdriverio" />