WebdriverIO API Reference for Axe DevTools for Web

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Reference for the APIs in the @axe-devtools/webdriverio package

Not for use with personal data

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.

note

You cannot select a nonstandard axe-core version and a custom rule set.

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', 'rgaav4', 'ttv5')

note

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 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.

analyzeUniversal Method

Performs an analysis and returns results in the Axe Universal Format. The existing analyze() method is unchanged.

analyzeUniversal(): Promise<UniversalExport>

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

These environment variables allow you to configure the usage service and change the properties of reported events.

Name	Type	Can Override	Description
`AXE_DISTINCT_ID`	String	—	A UUID identifier that remains the same for the logged-in user (unless it is regenerated)
`AXE_METRICS_URL`	String	—	The URL of the REST usage endpoint
`AXE_TRACK_USAGE`	Boolean	—	Enables usage service reporting (default is `false`)
`AXE_APPLICATION`	String	false	The application that was used to check for accessibility errors
`AXE_DEV_INSTANCE`	Boolean	true	Indicates whether this event is from a software developer's actions. Useful for marking and later removing events logged during development or testing.
`AXE_DEPARTMENT`	String	true	The user's department within the organization
`AXE_KEYCLOAK_ID`	String	false	The user's Keycloak ID
`AXE_LOGGED_IN`	Boolean	false	Records whether the user is logged in to the application under test
`AXE_ORGANIZATION`	String	true	The user's organization
`AXE_SESSION_ID`	String	false	A UUID identifying the user's session
`AXE_USER_ID`	String	false	A specific user's identity such as name or login ID
`AXE_USER_JOB_ROLE`	String	false	The user's job role
`AXE_USER_STATUS`	String	false	Status information you want to associate with the user

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