API Reference

This reference guide describes the APIs provided by the @axe-core/watcher package (also referred to as axe Watcher or just Watcher).

Configuration Functions

The configuration functions provided by Watcher allow you to modify your setup for the specified test framework as well as tailor how you want to run Watcher to suit your needs. See AxeConfiguration Interface for more information.

cypressConfig

Creates a configuration for Cypress.

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig Parameters

• config: Cypress.ConfigOptions & Configuration

  Intersection type of Cypress.ConfigOptions and Configuration.

Returns: Cypress.ConfigOptions

playwrightConfig

Creates a configuration for Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parameters

• opts: Configuration & LaunchOptions

  Intersection type of LaunchOptions and Configuration.

Returns: LaunchOptions

playwrightTest

Creates a configuration for Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parameters

• options: Options

  Options is an intersection type of Configuration and LaunchOptions.

Returns: ReturnValue

puppeteerConfig

Creates a configuration for Puppeteer.

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig Parameters

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Intersection type of LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, and Configuration.

Returns: Options

wdioConfig

Creates a WebdriverIO configuration.

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig Parameters

• arg: Options

  Options is an intersection type of RemoteOptions and Configuration.

Returns: RemoteOptions

wdioTestRunner

Creates a WebdriverIO Testrunner configuration.

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner Parameters

• params: unknown[]

  The params value is one of:

  1. An array containing one value, which is an intersection type of Options.Testrunner and Configuration.
  2. An array where the first array value is an AxeConfiguration and the second value is an Options.Testrunner.

Returns: Options.Testrunner

webdriverConfig

Creates a Selenium WebDriver configuration.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parameters

• arg: WebDriverArgs

  A Configuration extended to include a Selenium WebDriver Options member.

Returns: Options

Configuration Interface

The Configuration interface is used with the configuration functions and contains one property:

All of the configuration functions use this axe property to allow you to set up Watcher and configure your accessibility testing. See the next section, AxeConfiguration Interface, for more information.

AxeConfiguration Interface

The axe property (a parameter passed to the configuration functions) is the usual means of changing your AxeConfiguration for axe Watcher to configure accessibility testing. The following properties are contained in AxeConfiguration:

apiKey

The apiKey value is the only property that must be set in your AxeConfiguration. You can obtain its value from the Projects Page. See Managing Projects for more information.

buildID

The optional buildID property, when not null, allows parallel test runners to generate results that appear as a single test run in axe Developer Hub. In the case of parallel test runs, each test runner should share the same non-null buildID string, which causes each test run to concatenate its results with existing results for the same buildID and Git commit SHA. However, when buildID is null, multiple test runs overwrite existing results that have the same Git commit SHA.

You can usually obtain a usable buildID value from your continuous integration provider. For example, you can use these values:

• github.run_id

  Available within GitHub workflows. See github context in the GitHub documentation for more information.

• CIRCLE_PIPELINE_ID

  With CircleCI, the above value is available from your process's environment. See Built-in environment variables in the CircleCI documentation for more information.

  Other continuous integration environment variables you can use for buildID:

  Provider	Environment variable
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

excludeUrlPatterns

(Optional) Prevents any URL that matches any of the minimatch patterns in the excludeUrlPatterns array from being analyzed.

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

Examples

runContext

(Optional) Allows you to choose which elements are included and excluded from your page's accessibility analysis.

The value of runContext can be:

1. A single CSS selector for elements to be included in the analysis:

   axe: {
     runContext: '.main'
   }

2. An array of CSS selectors for elements to be included in the analysis:

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. A context object containing include and exclude properties (as shown in the above example). You can specify include or exclude or both. Each include or exclude can be a single CSS selector or an array of CSS selectors:

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

More details are available in the axe-core Context documentation.

runOptions

(Optional) The runOptions object allows the following subset of properties from the axe-core Options type:

• ancestry: Default is false. If true, the CSS selectors returned include the returned elements' ancestor elements.

  important

  If your page uses dynamic IDs or classes (element IDs or classes that change whenever the page is reloaded), you must specify ancestry as true so that axe Developer Hub can properly detect and track whether accessibility issues are duplicates because, by default, axe Developer Hub expects element IDs and classes to remain the same between test runs.

  When ancestry is true, axe Developer Hub instead uses the element's position within the DOM tree to locate the same element between test runs.

  The following shows an example of a selector when ancestry is false for an iframe element with an ID of main-iframe (<iframe id="main-iframe" ...>):

  iframe#main-iframe

  If ancestry is true, the selector would include the entire path from the root element, and there are no IDs or classes specified:

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly: This lets you limit which rules are executed by specifying names or tags. See runOnly below for more information.

• rules: Enable or disable rules using the enabled property. See rules below for more information.

The following shows an example of runOptions:

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: 'wcag2a'
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

The runOnly value (part of the runOptions object) can be one of the following:

1. A string representing the rule ID of the rule you'd like to use for accessibility analysis:

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. An array of strings representing the rule IDs of the rules you'd like to use:

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. An object with type and values properties. The type value is a string that can be rules, rule, tag, or tags. The values property can be a string or an array of strings representing the rule or tags you'd like to use for accessibility analysis. The following example shows using the runOnly object to limit accessibility testing to rules tagged as wcag2a:

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: 'wcag2a'
       }
     }  
   }

• For more examples of runOnly usage (with axe-core), see Options Parameter Examples
• For more information about available tag values, see axe-core Tags.
• For information about the rules, rule IDs, and tags, see Rule Descriptions

rules

The rules value (on the runOptions object) allows you to enable (enabled: true) or disable (enabled: false) specific rules during analysis, as shown below:

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

The sessionId property has been deprecated and should not be used. See buildID above.

Controller Classes

All of the classes in this section allow you to manually control the accessibility analysis of the pages.

PlaywrightController

The PlaywrightController class allows you to manually control test runs with Playwright and Playwright Test. You can start and stop automatic accessibility analysis as well as analyze pages that require additional setup.

For more information about Playwright, see the Playwright Documentation.

Constructor

new PlaywrightController(driver: Page): PlaywrightController

Parameters

• driver: Page

The driver value is a Playwright Page object.

Returns PlaywrightController

Methods

analyze

analyze(): Promise<void>

Analyzes the current page for accessibility errors. You call this method after you have set up a webpage for analysis (such as entered values in a form) and have turned off automatic analysis using the stop method.

Returns Promise<void>

flush

flush(): Promise<void>

Sends all of the results of the accessibility scan to axe Developer Hub. Should be called at the end of the test run to be certain the results have been sent to Deque's axe Developer Hub servers.

start

start(): Promise<void>

Resumes autoanalysis of webpages. You call this method when you want to resume autoanalyzing webpages for accessibility errors.

Returns Promise<void>

stop

stop(): Promise<void>

Returns Promise<void>

Stops autoanalysis of webpages. After you call the stop method, you can do any additional set up that your webpage may require and then call the analyze method to check the page for accessibility errors.

PuppeteerController

The PuppeteerController class allows manual control of your testing runs with Puppeteer. Manual control allows you to provide additional setup required by more complex web pages.

For more information about Puppeteer, see Puppeteer.

Constructor

new PuppeteerController(driver: Page): PuppeteerController

Parameters

• driver: Page

The driver value is a Puppeteer Page object.

Returns PuppeteerController

Methods

analyze

analyze(): Promise<void>

Analyzes the current page for accessibility errors. You call this method after you have set up a webpage for analysis (such as entered values in a form) and have turned off automatic analysis using the stop method.

Returns Promise<void>

flush

flush(): Promise<void>

Sends all of the results of the accessibility scan to axe Developer Hub. Should be called at the end of the test run to be certain the results have been sent to Deque's axe Developer Hub servers.

start

start(): Promise<void>

Resumes autoanalysis of webpages. You call this method when you want to resume autoanalyzing webpages for accessibility errors.

Returns Promise<void>

stop

stop(): Promise<void>

Returns Promise<void>

Stops autoanalysis of webpages. After you call the stop method, you can do any additional set up that your webpage may require and then call the analyze method to check the page for accessibility errors.

WdioController

The WdioController allows you to manually control WebdriverIO and WebdriverIO Testrunner test runs. For pages that require additional setup or configuration, you can stop automatic testing and manually analyze each page that requires such setup.

Constructor

new WdioController(driver: Page): WdioController

Parameters

• driver: Browser

Returns WdioController

Methods

analyze

analyze(): Promise<void>

Analyzes the current page for accessibility errors. You call this method after you have set up a webpage for analysis (such as entered values in a form) and have turned off automatic analysis using the stop method.

Returns Promise<void>

flush

flush(): Promise<void>

Sends all of the results of the accessibility scan to axe Developer Hub. Should be called at the end of the test run to be certain the results have been sent to Deque's axe Developer Hub servers.

start

start(): Promise<void>

Resumes autoanalysis of webpages. You call this method when you want to resume autoanalyzing webpages for accessibility errors.

Returns Promise<void>

stop

stop(): Promise<void>

Returns Promise<void>

Stops autoanalysis of webpages. After you call the stop method, you can do any additional set up that your webpage may require and then call the analyze method to check the page for accessibility errors.

WebdriverController

Constructor

new WebdriverController(driver: Page): WebdriverController

Parameters

• driver: WebDriver

The driver value is a Selenium WebDriver object.

Returns WebdriverController

Methods

analyze

analyze(): Promise<void>

Analyzes the current page for accessibility errors. You call this method after you have set up a webpage for analysis (such as entered values in a form) and have turned off automatic analysis using the stop method.

Returns Promise<void>

flush

flush(): Promise<void>

Sends all of the results of the accessibility scan to axe Developer Hub. Should be called at the end of the test run to be certain the results have been sent to Deque's axe Developer Hub servers.

start

start(): Promise<void>

Resumes autoanalysis of webpages. You call this method when you want to resume autoanalyzing webpages for accessibility errors.

Returns Promise<void>

stop

stop(): Promise<void>

Returns Promise<void>

Stops autoanalysis of webpages. After you call the stop method, you can do any additional set up that your webpage may require and then call the analyze method to check the page for accessibility errors.

Cypress Custom Commands

In the Cypress browser automation platform, the methods in the *Controller classes are implemented as custom commands. See Custom Commands on the Cypress documentation site for more information about implementing and using custom commands.

The following custom commands are implemented. Each custom command returns Chainable<void> to allow chaining with other Cypress commands.

These additional Cypress commands allow access to internal Cypress values:

• state()

  Internal Cypress state.

• subject

  The current Cypress subject. See Subject Management in the Cypress documentation for more information.

Cypress Command Example

The following example shows how to import the axe Developer Hub's Cypress commands from the @axe-core/watcher package and then call the axeWatcherFlush command at the end of each test (by placing it inside afterEach()):

// Import the axe-watcher commands.
require('@axe-core/watcher/dist/cypressCommands')

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})