Puppeteer API Reference for axe DevTools for Web

Constructors

There are two constructors for axe DevTools Puppeteer. This is the standard constructor:

AxeDevToolsPuppeteer(page: Frame | Page, options?: IOptions)

For the first argument, you must pass an instance of a Puppeteer Frame or Page. This is the target of the scan. The second argument is an optional object which can contain one of the following two properties:

1. axeSource (optional): a string of axe-core source code
2. rulesetID (optional): a stock ruleset ID

To use a specific version of axe-core (other than what is included as standard with your version of axe DevTools for Web), you can pass an axe-core source file in as an argument. First, create an axe source object by reading the axe-core file from the filesystem. Then, pass your axe DevTools instance to the axe source object:

const axeSource = fs.readFileSync('./axe-3.0.js', 'utf8');
const builder = new AxeDevToolsPuppeteer(page, { axeSource });

If you wish to use a predefined ruleset other than the standard, you can pass the rulesetID to your axe DevTools instance:

const builder = new AxeDevToolsPuppeteer(page, { rulesetID: 'wcag2' });

An alternate constructor can open a page and perform the CSP bypass for you. Instead of passing it a preloaded page, you pass a Browser object and URL. It automatically closes the page after analyze is called. Additionally, it automatically performs the CSP bypass. This is its constructor:

loadPage(browser: Browser, url: string, options?: IOptions)

This constructor includes the same options for alternate axe-core sources or rulesets, and these arguments are passed in the same way as above. Here is a sample file using the alternate constructor, which logs the scan results to the console:

const puppeteer = require('puppeteer');
const { AxeDevToolsPuppeteer } = require('@axe-devtools/puppeteer');

(async () => {
    //launch puppeteer web driver
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    //launch page for testing
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results = await new AxeDevToolsPuppeteer(page).analyze();
    //log results to console
    console.log(results);

    //close browser
    browser.close();
})();

analyze

.analyze([callback: (Error | null[, Object]) => void])

This method performs an analysis and passes any encountered error and/or the result object to the provided callback or promise function. Be aware it does not chain because its operation is asynchronous.

The following example uses the returned promise and logs the results object to the console:

new AxeDevToolsPuppeteer(page)
  .analyze()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

This example shows the analyse() method with a callback function:

new AxeDevToolsPuppeteer(page).analyze(function(err, results) {
  if (err) {
    // Handle error somehow
  }
  console.log(results);
});

Scoping

Two options exist for scoping your axe DevTools scans: include and exclude. They scope the scans to the specified CSS selectors and can be chained together. They both use single CSS selectors or arrays of CSS selectors, so you can completely customize your scan.

include

.include(selector: string | string[])

With the include chain method, only elements selected by the CSS selector or array of CSS selectors will be scanned. This is useful for checking single instances of componentized pages or limiting results to current development.

This example below shows that the scope is limited to elements within the results-panel class:

new AxeDevToolsPuppeteer(page).include('.results-panel');

exclude

.exclude(selector: string | string[])

The exclude chain method removes elements selected by a CSS selector or an array of CSS selectors from the page to be scanned. Like the include method, single selectors or an array of selectors can be passed in. This method can also be chained with the include method.

The example call below shows the scope excluding h2 elements with the results-panel class:

new AxeDevToolsPuppeteer(page).include('.results-panel h2');

Rule Configuration

withRules

.withRules(rules: string | string[])

This method limits the analysis to the specified rule ID or rule IDs. For a complete list of rules and their descriptions, visit the axe-core rule documentation.

In the following example, only the html-lang and image-alt rules will be tested:

new AxeDevToolsPuppeteer(page).withRules(['html-lang', 'image-alt']);

withTags

.withTags(tags: string | string[])

The withTags method limits the scan to the rules associated with the tag or tags specified. A complete list of ruleset tags can be found within the axe-core documentation.

The following example tests for only WCAG 2.0 Level A rules:

new AxeDevToolsPuppeteer(page).withTags('wcag2a');

disableRules

.disableRules(rules: string | string[])

This method removes a specific rule or an array of rules from the current list of rules to be used. Rules are specified by their rule ID. Subsequent calls to this method will override previous calls. A complete list of rule IDs and their descriptions can be found in the axe-core rule documentation.

The following example disables color contrast verification.

new AxeDevToolsPuppeteer(page).disableRules('color-contrast');

Additionally, disableRules can be chained with other rule configuration methods to modify user-configured rulesets.

In the following example, the ruleset is modified to use only WCAG 2.0 A and AA rules, then removes the color contrast verification rule:

new AxeDevToolsPuppeteer(page)
  .withTags(['wcag2a', 'wcag2aa'])
  .disableRules('color-contrast');

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 AxeDevToolsPuppeteer(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 AxeDevToolsPuppeteer(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

The enableTracking() method allows users to opt in to send data to the usage service.

.enableTracking(state: boolean)

This example shows the enableTracking method paired with the analyze method, which logs the results object to the console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setTrackingUrl

The setTrackingUrl() method allows users to change where the usage metrics data are sent.

.setTrackingUrl(url: string)

This example shows the setTrackingUrl() method with the analyze() method and logs the results object to the console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setTrackingUrl('https://foobar.biz')
  .analyze()
  .then(function(results) {
    console.log(results)
  })

setDistinctId

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

.setDistinctId(distinctId: string)

This example shows the setDistinctId method with the analyse method and logs the results object to the console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setDistinctId('foobar')
  .analyze()
  .then(function(results) {
    console.log(results)
  })