WebDriverJS API Reference for axe DevTools for Web

Constructor

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

Axe DevTools WebDriverJS constructor:

AxeDevToolsBuilder(driver:WebDriver, String:ruleset|Object:axe (optional))

You must pass an instance of a Selenium WebDriver as the first argument. The second optional argument may be either a ruleset ID or an axe object. If you do not provide a second argument, you must configure the @axe-devtools/script-builder custom rule configuration file, or the constructor will throw an exception.

These examples show how to use the constructor:

// instantiate with the Section 508 rule set
const builder = new AxeDevToolsBuilder(driver, '508');

// or with a specific axe instance
const axe = require('../axe-core-2.3.0');
const builder = new AxeDevToolsBuilder(driver, axe);

Custom Rules

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

analyze

The analyze() method runs the analysis and returns accessibility scan results.

analyze(): Promise<axe.AxeResults>

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

Chain Options

Two options exist for scoping your axe DevTools scans. You can choose to include or exclude specific CSS scopes. The chain methods (below) on the constructor make this possible.

include

new AxeDevToolsBuilder(driver).include('<CSS-Selector>');

Adds a CSS selector to the list of elements to include in the analysis. Elements outside the scope passed to include() will not be scanned.

exclude

new AxeDevToolsBuilder(driver).exclude('<CSS-Selector>');

Add a CSS selector to the list of elements to exclude from analysis. Only elements outside the scope passed to exclude() will be scanned.

These methods can be chained to refine the scan scope further, as shown below:

new AxeDevToolsBuilder(driver).include('<CSS-Selector>').exclude('<Inner-CSS-Selector>');

In this example, all elements within <CSS-Selector> would be scanned, except for the elements inside <Inner-CSS-Selector>.

Rule Configuration

The rule configuration methods overwrite the standard rule configuration. Additional calls with these methods will overwrite previous calls.

withRules

The withRules() method limits analysis to only those rules with the specified rule IDs. It accepts a string for a single rule ID or an array of multiple rule IDs.

These examples show using withRules with a single rule ID and an array of rule IDs:

//with a single rule ID
AxeDevToolsBuilder(driver).withRules('html-lang');

//with an array of rule IDs
AxeDevToolsBuilder(driver).withRules(['html-lang', 'image-alt']);

withTags

The withTags() method limits analysis to only those rules associated with the provided tag. Accepts a single tag or an array of tags, as shown below:

//with a single tag
AxeDevToolsBuilder(driver).withTags('wcag2a');

//with an array of tags
AxeDevToolsBuilder(driver).withTags(['wcag2a', 'wcag2aa']);

disableRules

AxeDevToolsBuilder.disableRules(rules: RuleID[]): AxeDevToolsBuilder

The disableRules() method causes the array of rules provided to be skipped when running an analysis.

axe-core options

options

.options(options: Axe.RunOptions)

The options method specifies options to be used by axe.run. It will override any other configured options, including calls to withRules and withTags. See the axe-core API documentation for information.

new AxeDevToolsBuilder(page).options({
  checks: { 'valid-lang': ['orcish'] }
});

configure

.configure(config: Axe.Spec)

The configure method injects an axe configuration object to modify the ruleset before an analysis. Subsequent calls to this method will invalidate previous ones by calling axe.configure() and replacing the configuration object. See axe-core API documentation for the object's structure.

The following example creates a new axe-core configuration and passes it to axe DevTools to be used for scanning:

const config = {
  checks: [Object],
  rules: [Object]
};
const results = await new AxeDevToolsBuilder(page).configure(config).analyze();

Usage Service

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 send data to the usage service.

.enableTracking(state: boolean)

AxeDevToolsBuilder(driver).enableTracking(true)

setTrackingUrl

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

.setTrackingUrl(url: string)

AxeDevToolsBuilder(driver).setTrackingUrl('https://foobar.biz')

setDistinctId

This method allows users to change the distinct ID being stored or used.

.setDistinctId(distinctId: string)

AxeDevToolsBuilder(driver).setDistinctId('foobar')