Playwright API Reference for axe DevTools for Web

Constructor

In the standard configuration, the only argument required to be passed to the constructor is the Playwright 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 as well.

Axe DevTools Playwright constructor:

AxeDevToolsBuilder({ page: PlaywrightPage, source: string, rulesetId: AxeDevtoolsRulesetID})

You must pass an instance of PlaywrightPage as the first argument. The second 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. Must be called with the new keyword.

// instantiate with the Section 508 rule set
const builder = new AxeDevToolsBuilder({ page, rulesetId: '508' });

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

Custom Rules

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

analyze

AxeDevToolsBuilder.analyze(): Promise<axe.Results | Error>

Performs an analysis and passes the result object and any errors.

new AxeDevToolsBuilder({ page })
  .analyze()
  .then(results => {
    console.log(results);
  })
  .catch(e => {
    // Do something with error
  });

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 make this possible. These methods can be chained to create complex, focused scans.

include

AxeDevToolsBuilder.include(selector: String | String[])

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.

new AxeDevToolsBuilder({ page }).include('<CSS-Selector>');

exclude

AxeDevToolsBuilder.exclude(selector: String | String[])

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.

new AxeDevToolsBuilder({ page }).exclude('<CSS-Selector>');

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

new AxeDevToolsBuilder({ page }).include('<CSS-Selector>').exclude('<Inner-CSS-Selector>');

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

AxeDevToolsBuilder.withRules(rules: String|Array)

Limits analysis to only those with the specified rule IDs. Accepts a string of a single rule ID or an array of multiple rule IDs.

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

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

withTags

AxeDevToolsBuilder.withTags(tags: String|Array)

Limits analysis to only those rules tagged with the provided tag. Accepts a single tag or an array of tags.

//with a single tag
AxeDevToolsBuilder({ page }).withTags('wcag2a');

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

disableRules

AxeDevToolsBuilder.disableRules(rules: String|Array)

Skips verification of the rules provided. Accepts a string representing a single rule ID or an array of multiple rule IDs. Subsequent calls to AxeDevToolsBuilder.options(), AxeDevToolsBuilder.disableRules() will override specified options.

new AxeDevToolsBuilder({ page }).disableRules('color-contrast');

axe-core Options

These options access the underlying axe-core configuration. For more information about these options, see the axe-core documentation.

configuration

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

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

options

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

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

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

.enableTracking(state: boolean)

AxeDevToolsBuilder({ page }).enableTracking(true)

setTrackingUrl

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

.setTrackingUrl(url: string)

AxeDevToolsBuilder({ page }).setTrackingUrl('https://foobar.biz')

setDistinctId

This method allows users to change which distinct ID is stored or used.

.setDistinctId(distinctId: string)

AxeDevToolsBuilder({ page }).setDistinctId('foobar')