Playwright API Reference

High-level details of the axe DevTools Playwright 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 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: Page, source: string, rulesetId: AxeDevtoolsRulesetID})

You must pass an instance of playwright 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, then 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

Chain Options

Two options exist for scoping your axe DevTools scans. You can chose to include or exclude specific CSS scopes. The below chain methods on the constructor make this possible. These methods can be chained with each other to create complex enclaves and exclaves of scan area.

Scope Include

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

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

Scope Exclude {#scope-Exclude}

new AxeDevToolsBuilder({ page }).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 with each other to further refine scan scope.

new AxeDevToolsBuilder({ page }).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

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

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

Include Tags

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

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

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

Usage Service

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)

AxeDevToolsBuilder({ page }).enableTracking(true)

Set Tracking Url

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

.setTrackingUrl(url: string)

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

Set Distinct ID

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

.setDistinctId(distinctId: string)

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