WebdriverIO API Reference for axe DevTools for Web

Constructor

In the standard configuration, the only argument required to be passed to the WebdriverIO 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.

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')

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 in the axeSource option. All axe-core versions can be fetched from npm or through unpkg by visiting http://unpkg.com/axe-core@<version>/axe.js (replace <version> 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 });

analyze Method

This method runs the analysis and ultimately returns accessibility scan results.

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

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

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 include or exclude specific CSS scopes and/or ignore iframes. The chain methods (below) on the constructor make this possible.

disableFrame

AxeDevToolsWebdriverIO.disableFrame(selector: string): AxeDevToolsWebdriverIO

Disable injecting axe-core into frames matching the given CSS selector. This method may be called any number of times.

include

AxeDevToolsWebdriverIO.include(selector: string): AxeDevToolsWebdriverIO

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

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.

withRules

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

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

withTags

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

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

disableRules

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 about these options, see the axe-core documentation.

configure

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

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

options

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

The runOptions to directly pass to axe.run(). See the axe-core documentation for use. Will override any other configured options, including calls to AxeDevToolsWebdriverIO.withRules() and AxeDevToolsWebdriverIO.withTags().

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

enableTracking

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

.enableTracking(state: boolean): AxeDevToolsWebdriverIO

setTrackingUrl

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

.setTrackingUrl(url: string): AxeDevToolsWebdriverIO

setDistinctId

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

.setDistinctId(distinctId: string): AxeDevToolsWebdriverIO