Puppeteer API Reference

Overview of axe DevTools Puppeteer API

This module uses a chainable API to add functionality in addition to the standard scan configuration.

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 element that will be scanned. The second argument is 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, you can pass an axe-core source file in as an argument. This will cause your axe DevTools instance to run this axe-core version instead of the version included automatically as a dependency. To do this, first, create an axe source object by reading the axe-core file from the filesystem. Then, pass your axe DevTools instance 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 is available which opens a page and performs the CSP bypass for you. Instead of passing it in a preloaded page, this constructor is passed the browser and a URL to open. 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)

It 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 and logging the scan results to 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();
})();

Scoping

Two options exist for scoping your axe DevTools scans: include and exclude. They scope the scans around CSS selectors, and can be chained with each other. They both take in single scopes, or arrays of scopes so you can customize your scan area to be exactly what you wish to scan.

Include

.include(selector: string | string[])

With the include chain method, only elements within the scope of the element or elements passed in as arguments will be scanned. This is extremely useful for checking single instances of componentized pages or limiting results to current development tasks. This example call shows the scope being limited to elements with the results panel class.

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

Exclude

.exclude(selector: string | string[])

This chain method removes the scope of the element or elements passed in from the area of the page to be scanned. Similar to the include method, single selectors or an array of selectors can be passed in. This can also be chained with the include method. This example call shows the scope excluding h2 elements with the results panel class.

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

Rule Configuration

Axe-core Run Options

.options(options: Axe.RunOptions)

This 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 on its structure.

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

Rule Selection by Rule ID

.withRules(rules: string | string[])

This method limits the analysis to only the rule or rule IDs passed in. Additional scans with rule configuration modification will override this call. For a complete list of rules and their descriptions visit the axe-core rule documentation. In this example, only the language and image alt rules will be tested.

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

Rule Selection by Tag

.withTags(tags: string | string[])

This method limits the scan to only the rules specified within the tag or tags passed in. Future modification to the rule configuration will override this call. A complete list of ruleset tags can be found within the axe-core documentation. This example tests for only WCAG 2.0 single-A based rules.

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

Disabling Rules by Rule ID

.disableRules(rules: string | string[])

This method removes specific a rule or an array of rules from the existing rule configuration to be used. Rules are specified by their rule ID. Subsequent modification of the rule configuration will override this call. A complete list of rule IDs and their descriptions can be found in the axe-core rule documentation. This example disables color contrast verification.

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

Additionally, this functor can be chained with other rule configuration methods to modify user configured rulesets. In this example, only the ruleset is first modified to use only WCAG 2.0 A and AA based rules, and then removes color contrast verification.

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

Modify axe-core Configuration

.configure(config: Axe.Spec)

This 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 config object. See axe-core API documentation for documentation on the object structure. This example creates a new axe-core configuration and passes it to axe DevTools to be used in the scan.

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

Analysis

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

This method performs the analysis and passes any encountered error and/or the result object to the provided callback function or promise function. Be aware, it does not chain as the operation is asynchronous. This 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 analysis method paired with a callback function.

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

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)

This example shows the enableTracking method paired with analysis method which logs the results object to the console

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

Set Tracking Url

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

.setTrackingUrl(url: string)

This example shows the setTrackingUrl method pair with analysis method which logs the results object to the console

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

Set Distinct ID

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

.setDistinctId(distinctId: string)

This example shows the setDistinctId method pair with analysis method which logs the results object to the console

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

More Reading

This documentation constitutes a high level overview of the exposed API. To ensure you're reading the most up-to-date and comprehensive API docs, refer to the generated TypeScript definitions at dist/index.d.ts. If the dist folder does not exist, run npm run build first.