WebDriverIO API Reference

High-level details of the axe DevTools WebdriverIO API and usage instructions

This module uses a chainable API to add functionality in addition to the standard scan configuration.

Constructor

In the standard configuration, the only argument required to be passed to the axe DevTools constructor is the WebDriverIO instance if you wish to use a different axe-core version than originally included or a custom ruleset you can pass these options into the constructor.

Axe DevTools WebdriverIO constructor:

AxeDevToolsWebdriverIO(options: Options)

The Options interface is an object which contains the following properties:

• client (required): A WebdriverIO client
• axeSource (optional): a string of axe-core source code
• rulesetID (optional): a ruleset ID ('wcag2', 'wcag2.1', 'wcag2.2', 'wcag2aaa', 'wcag2.1aaa', 'wcag2.2aaa', '508', 'en301549', 'ttv5')

You may not provide both axeSource and rulesetID. The two are mutually exclusive.

Defining the axe-core version

By default, @axe-devtools/webdriverio will use the latest available version of axe-core. To configure a different version of axe-core, pass the axe source property in as the axeSource option. All axe-core versions can be fetched from npm or through unpkg, by going to http://unpkg.com/axe-core@<version>/axe.js (replace with the version number). All axe-core versions after 2.1.0 are supported. This is an example of initializing axe DevTools WebdriverIO with axe-core 2.3.0 from a file located in the test file's parent directory.

const axeSource = require('../axe-core-3.5.0').source;
const axeDevTools = new AxeDevToolsWebdriverIO({ client, axeSource });

Custom Rules

For information on using custom rules with axe DevTools, read the guide on custom ruleset generation and integration in the CLI guide

Chain Options

Several options exist for scoping your axe DevTools scans. You can chose to include or exclude specific CSS scopes and/or ignore Iframes. The below chain methods on the constructor make this possible.

Iframe disable

AxeDevToolsWebdriverIO#disableFrame(selector: string): AxeDevToolsWebdriverIO

Disable injecting axe-core into an frame(s) matching the given CSS selector. This method may be called any number of times.

Scope Include

AxeDevToolsWebdriverIO#include(selector: string): AxeDevToolsWebdriverIO

Selector to include in analysis. This may be called any number of times.

Scope Exclude

AxeDevToolsWebdriverIO#exclude(selector: string): AxeDevToolsWebdriverIO

Selector to exclude in analysis. This may be called any number of times.

Rule Configuration

These options modify the rule configuration for the chosen ruleset. These options overwrite the standard rule configuration and will modify your results. Additional calls with these methods will overwrite previous calls.

Include Rules

AxeDevToolsWebdriverIO#withRules(rules: RuleID[]): AxeDevToolsWebdriverIO

Limit analysis to only the specified rules. Cannot be used with AxeDevToolsWebdriverIO#withTags.

Include Tags

AxeDevToolsWebdriverIO#withTags(tags: axe.TagValue[]): AxeDevToolsWebdriverIO

Limit analysis to only the specified tags. Cannot be used with AxeDevToolsWebdriverIO#withRules.

Exclude Rules

AxeDevToolsWebdriverIO#disableRules(rules: RuleID[]): AxeDevToolsWebdriverIO

Set the list of rules to skip when running an analysis.

Axe-core Options

These options access the underlying axe-core configuration. For more information into these options we suggest reading the axe-core documentation

Axe-core configuration

AxeDevToolsWebdriverIO#configure(config: axe.Spec): AxeDevToolsWebdriverIO

Set configuration for axe-core. This value is passed directly to axe.configure().

Axe-core options

AxeDevToolsWebdriverIO#options(runOptions: axe.RunOptions): AxeDevToolsWebdriverIO

Options to directly pass to axe.run. See API documentation for axe-core for use. Will override any other configured options, including calls to AxeDevToolsWebdriverIO#withRules and AxeDevToolsWebdriverIO#withTags.

Analyze Function

This method runs the analysis and ultimately returns the scan results

analyze(client: webdriverio.Client): Promise<axe.AxeResults>

Run an analysis using default configuration on the given client. A Promise is returned which resolves with the result set returned by axe-core.

Usage Service

The Usage Service allows you to gain insight into axe DevTools usage trends within your organization.

By default the usage-service is disabled, and the default url is https://usage.deque.com.

Environment variables

This method allows users to change specific values of the usage service via environment variables

Enable Tracking

This method allows users to opt in to sending data to the usage service

.enableTracking(state: boolean): AxeDevToolsWebdriverIO

Set Tracking Url

This method allows users to change where the usage metrics data are being sent to

.setTrackingUrl(url: string): AxeDevToolsWebdriverIO

Set Distinct ID

This method allows users to change the distinct id being stored/used

.setDistinctId(distinctId: string): AxeDevToolsWebdriverIO