WebdriverIO API

Overview

Use the WebdriverIO API configuration to customize how Level CI runs accessibility analysis in your WebdriverIO tests. You can configure Level CI globally with levelSetup() or override settings for individual tests with levelAnalyze().

API Methods

levelAnalyze

levelAnalyze(browser: Browser, config?: LaunchConfig): Promise<AnalysisResultData>

Runs a static accessibility analysis on the current page and generates a folder with analysis result data.

Properties

Property	Type	Default	Description
browser	WebdriverIO.Browser	—	WebdriverIO Browser object to analyze
config	LaunchConfig	{}	Optional configuration object

Returns

Returns a Promise, which should resolve, otherwise return value will contain error object.

Usage

Important: Make sure to use levelAnalyze after your tests have run successfully. If you add it to some kind of an afterEach hook, add a condition to check the success of test execution.

Otherwise, every rerun of a test, if you have retries, will produce a new report that is to be uploaded and processed, even when the test fails in the middle of execution.

levelSetup

levelSetup(config: LaunchConfig): void

Configure global settings for all Level CI analysis runs. Use this in your WebdriverIO support file or before tests for a clean setup.

Properties

Property	Type	Default	Description
config	LaunchConfig	—	Global configuration object

Returns

No return value (void). Configuration is stored globally and applied to all subsequent levelAnalyze calls.

Note: Global configuration can be overridden per test. For this provide config per levelAnalyze call. Arrays and objects are merged with test-level config.

Usage

You can use levelSetup in your support file so all tests use the same defaults.

Config

LaunchConfig

Configuration options

Option	Type	Description
switchOff	boolean	Disable rules check globally or per specific test. Default: false. Environment variable: LEVEL_CI_SWITCH_OFF. Example value: true.
reportPath	string	Folder path to store analysis artifacts. Default: level-ci-reports. Environment variable: LEVEL_CI_REPORT_PATH. Example value: my-custom-report-path.
ignoreUrls	RegExp[]	Skip analysis for URLs matching these patterns. Example value: [/home/, /settings\/privacy/, /articles\/*/].
customTags	string[]	Add custom tags for scan identification. Example values: ['alpha', 'beta', 'scenario-1'].
stableSelectorAttributes	string[]	Add to reliably identify elements with dynamic IDs. Example values: ['data-testid'].

Custom tags

If you pass scenario-1 as a custom tag, you will see it among the other tags for the newly found issues on the dashboard. This way you can identify which issue appeared, while testing scenario-1.

Stable selector attributes

Flaky issues often occur when elements have dynamic IDs. Level CI tracks elements across scans to monitor accessibility issues, but if an element’s id changes between scans, it treats it as a new element. This causes old issues to close and new issues to open for the same element.

Component-level screenshots (experimental)

To enable component-level screenshots for detected accessibility issues, add the experimental.elementScreenshots option to your levelAnalyze() configuration.

This setting is currently experimental. Enabling component-level screenshots may increase scan execution time because screenshots are captured during the accessibility analysis.

Examples

Use these examples to set a custom report path, add stable selector attributes, disable rule checks, add tags, and ignore specific URLs during analysis.

Method levelAnalyze

|
levelAnalyze(browser: Browser, config?: LaunchConfig): Promise<AnalysisResultData>
        

Usage levelAnalyze

|
it('homepage accessibility', async () => {
  await levelAnalyze(browser, {
    reportPath: './custom-reports-folder',
  })
})
        

Success condition afterEach hook

|
afterTest: async (_test, _context, { passed }) => {
  if (passed) {
    await levelAnalyze(browser)
  }
}
        

Method levelSetup

|
levelSetup(config: LaunchConfig): void
        

Option 1 Pass browser to analyze function

|
// webdriverio/support/e2e.ts
import { levelSetup } from '@level-ci/a11y-webdriverio'
 
levelSetup({
  reportPath: 'level-ci-reports-custom',
  stableSelectorAttributes: ['data-testid'],
})
        

Then 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)
  })
})
        

Option 2 Override config per test

|
await levelAnalyze(browser, {
  reportPath: './per-test-reports',
  customTags: ['smoke'],
})
        

Config LaunchConfig

|
interface LaunchConfig {
  switchOff?: boolean
  reportPath?: string
  ignoreUrls?: RegExp[]
  customTags?: string[]
  stableSelectorAttributes?: string[]
}
        

Stable selector attributes Usage

|
<p data-testid="hello-paragraph-element">
  Hello from an element with a dynamic id attribute
</p>
        

|
await levelAnalyze(browser, {
  stableSelectorAttributes: ['data-testid'],
})
        

Set custom report path Option 1: Globally with levelSetup

|
levelSetup({
  reportPath: './custom-reports-folder',
})
        

Set custom report path Option 2: Per test with levelAnalyze

|
await levelAnalyze(browser, {
  reportPath: './custom-reports-folder',
})
        

Set custom report path Option 3: Using environment variable

|
LEVEL_CI_REPORT_PATH=./custom-reports
        

Add stable selector attributes Option 1: Globally with levelSetup

|
levelSetup({
  stableSelectorAttributes: ['data-testid', 'data-qa'],
})
        

Add stable selector attributes Option 2: Per test with levelAnalyze

|
await levelAnalyze(browser, {
  stableSelectorAttributes: ['data-testid', 'data-qa'],
})
        

Disable rule check Option 1: Globally with levelSetup

|
levelSetup({
  switchOff: true,
})
        

Disable rule check Option 2: Per test with levelAnalyze

|
await levelAnalyze(browser, {
  switchOff: true,
})
        

Disable rule check Option 3: Using environment variable

|
LEVEL_CI_SWITCH_OFF=true
        

Add specific tags for this analysis run Option 1: Globally with levelSetup

|
levelSetup({
  customTags: ['my-tag', 'regression'],
})
        

Add specific tags for this analysis run Option 2: Per test with levelAnalyze

|
await levelAnalyze(browser, {
  customTags: ['my-tag', 'regression'],
})
        

Ignore specific URLs during analysis Option 1: Globally with levelSetup

|
levelSetup({
  ignoreUrls: [/localhost:3000/, /example.com/],
})
        

Ignore specific URLs during analysis Option 2: Per test with levelAnalyze

|
await levelAnalyze(browser, {
  ignoreUrls: [/localhost:3000/, /example.com/],
})
        

Enable component-level screenshots Experimental

|
    await levelAnalyze(browser, {
      experimental: {
        elementScreenshots: true,
      },
    })