@axe-core/webdriverio

Provides a chainable axe API for WebdriverIO and automatically injects into all frames.

Feature Deprecation Notice

Support for @wdio/sync is deprecated and testing for it will be removed in a future release.

Getting Started

Install Node.js if you haven't already.

Download and install any necessary browser drivers on your machine's PATH. More on WebdriverIO setup.

Install WebdriverIO: npm install webdriverio

Install @axe-core/webdriverio: npm install @axe-core/webdriverio

Usage

This module uses a chainable API to assist in injecting, configuring, and analyzing axe with WebdriverIO. As such, it is required to pass an instance of WebdriverIO.

Here is an example of a script that will drive WebdriverIO to a page, perform an analysis, and then log results to the console.

const { AxeBuilder } = require('@axe-core/webdriverio');
const { remote } = require('webdriverio');

(async () => {
  const client = await remote({
    logLevel: 'error',
    capabilities: {
      browserName: 'chrome',
      'goog:chromeOptions': {
        args: ['headless', 'disable-gpu']
      }
    }
  });
  await client.url('https://dequeuniversity.com/demo/mars/');

  try {
    const results = await new AxeBuilder({ client }).analyze();
    console.log(results);
  } catch (e) {
    // do something with the error
  }

  client.deleteSession();
})();

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

Performs analysis and passes any encountered error and/or the result object.

new AxeBuilder({ client }).analyze((err, results) => {
  if (err) {
    // Do something with error
  }
  console.log(results);
});

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

AxeBuilder({ client: WebdriverIO.BrowserObject })

Constructor for the AxeBuilder helper. You must pass an instance of WebdriverIO as the first argument.

const builder = new AxeBuilder({ client });

AxeBuilder#include(selector: String)

Adds a CSS selector to the list of elements to include in analysis

new AxeBuilder({ client }).include('.results-panel');

AxeBuilder#exclude(selector: String)

Add a CSS selector to the list of elements to exclude from analysis

new AxeBuilder({ client }).exclude('.another-element');

AxeBuilder#options(options: axe.RunOptions)

Specifies options to be used by axe.run. Will override any other configured options. including calls to AxeBuilder#withRules() and AxeBuilder#withTags(). See axe-core API documentation for information on its structure.

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

AxeBuilder#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. Subsequent calls to AxeBuilder#options, AxeBuilder#withRules or AxeBuilder#withRules will override specified options.

new AxeBuilder({ client }).withRules('html-lang');

new AxeBuilder({ client }).withRules(['html-lang', 'image-alt']);

AxeBuilder#withTags(tags: String|Array)

Limits analysis to only those with the specified rule IDs. Accepts a String of a single tag or an Array of multiple tags. Subsequent calls to AxeBuilder#options, AxeBuilder#withRules or AxeBuilder#withRules will override specified options.

new AxeBuilder({ client }).withTags('wcag2a');

new AxeBuilder({ client }).withTags(['wcag2a', 'wcag2aa']);

AxeBuilder#disableRules(rules: String|Array)

Skips verification of the rules provided. Accepts a String of a single rule ID or an Array of multiple rule IDs. Subsequent calls to AxeBuilder#options, AxeBuilder#disableRules will override specified options.

new AxeBuilder({ client }).disableRules('color-contrast');

AxeBuilder#setLegacyMode(legacyMode: boolean = true)

Set the frame testing method to "legacy mode". In this mode, axe will not open a blank page in which to aggregate its results. This can be used in an environment where opening a blank page is causes issues.

With legacy mode turned on, axe will fall back to its test solution prior to the 4.3 release, but with cross-origin frame testing disabled. The frame-tested rule will report which frames were untested.

Important Use of .setLegacyMode() is a last resort. If you find there is no other solution, please report this as an issue.

const axe = new AxeBuilder({ client }).setLegacyMode();
const result = await axe.analyze();
axe.setLegacyMode(false); // Disables legacy mode

Shadow DOM support

@axe-core/webdriverio is unable to support iframes in shadow DOM elements due to lack of shadow DOM support in webdriverio devtools protocol.