API Reference

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

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.

autoAnalyze

Set this value to false to prevent pages from automatically being analyzed. For more information about manual mode, see Controlling When Page Analysis Occurs.

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

configurationOverrides

(Optional) Overrides values set in the global configuration. See the ConfigurationOverrides Interface for more information.

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.

timeout

The timeout object (of type Timeouts) in AxeConfiguration sets the timeout values in milliseconds for the respective controller methods (or custom commands for Cypress). (See the Controller Classes for information on the controller classes and the Cypress Custom Comments for information on Cypress custom commands.) When a timeout expires, the test fails with a message indicating that the timeout was exceeded. You can increase the timeout to avoid the error.

This example sets the analyze timeout to 8 seconds, flush to 15 seconds, start to 10 seconds, and stop to 10 seconds. (The default values are shown in the table under Timeouts Interface.)

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

Controller Classes

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.

ConfigurationOverrides Interface

The ConfigurationOverrides interface allows you to override your organization's global configuration settings for individual test runs. This property must be used in accordance with the permissions set in your enterprise's global configuration.

accessibility_standard

Sets the accessibility standard to test against. Available options:

• 'All' - Tests against all available standards
• 'WCAG 2.2 AAA'
• 'WCAG 2.2 AA'
• 'WCAG 2.2 A'
• 'WCAG 2.1 AAA'
• 'WCAG 2.1 AA'
• 'WCAG 2.1 A'
• 'WCAG 2.0 AAA'
• 'WCAG 2.0 AA'
• 'WCAG 2.0 A'
• 'Trusted Tester v5'
• 'EN 301 549'

Your organization must allow overriding of this setting in the global configuration, and the selected standard must be among the permitted options.

axe_core_version

Specifies which version of axe-core to use for testing. Available options include:

• 'latest' - Latest supported version currently bundled with axe Watcher
• Specific versions from 4.4.0 and later (e.g., '4.10.2', '4.9.1', etc.)

Your organization must allow overriding this setting in the global configuration, and the selected version must be among the permitted options.

best_practices

Enables or disables best practice rules for the test run. Best practices enhance accessibility but aren't part of formal standards. Your organization must allow overriding of this setting for it to take effect.

experimental_rules

Enables or disables experimental rules for the test run. Experimental rules are still in development and may produce false positives. Your organization must allow overriding of this setting in the global configuration for it to take effect.

Controller Classes

The following classes extend the Controller abstract class to allow you to control the accessibility analysis of your website's pages manually.

Controller

abstract class Controller

The Controller abstract class contains the methods for controlling page analysis. Each of the concrete classes extends this class, so the following methods are available in all of the concrete classes.

analyze

analyze(): Promise<void>

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

analyze Returns

Promise<void>

analyze Equivalent Cypress command

cy.axeWatcherAnalyze()

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 ensure the results have been sent to Deque's axe Developer Hub servers.

flush Returns

Promise<void>

flush Equivalent Cypress command

cy.axeWatcherFlush()

start

start(): Promise<void>

Resumes auto-analysis of web pages. You call this method when you want to resume auto-analyzing web pages for accessibility errors.

start Returns

Promise<void>

start Equivalent Cypress command

cy.axeWatcherStart()

stop

stop(): Promise<void>

Stops auto-analysis of web pages. After you call the stop method, you can do any additional setup your web page may require and then call the analyze method to check the page for accessibility errors.

stop Returns

Promise<void>

stop Equivalent Cypress command

cy.axeWatcherStop()

PlaywrightController

The PlaywrightController class allows you to manually control accessibility analysis for test runs with Playwright and Playwright Test. You can start and stop automatic accessibility analysis and 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

See Controller for the methods implemented in the abstract base class.

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

See Controller for the methods implemented in the abstract base class.

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: Browser): WdioController

Parameters

• driver: Browser

Returns WdioController

See Controller for the methods implemented in the abstract base class.

WebdriverController

Constructor

new WebdriverController(driver: WebDriver): WebdriverController

Parameters

• driver: WebDriver

The driver value is a Selenium WebDriver object.

Returns WebdriverController

See Controller for the methods implemented in the abstract base class.

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.

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()
})

Timeouts Interface

The timeout object (of type Timeouts) in the AxeConfiguration interface allows users to change the timeout values (in milliseconds) for the respective controller functions or the Cypress custom commands.

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}