API Reference for the JavaScript and TypeScript version of Watcher

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

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

(Required) The apiKey value is one of two properties (apiKey and projectId) that must be set in your AxeConfiguration. You can obtain its value from the Manage API Keys Page .

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY
}

autoAnalyze

(Optional) Set this value to false to prevent pages from automatically being analyzed. For more information about manual mode, see Control Your Scans.

axe: {
  autoAnalyze: false
}

buildID

(Optional) The 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.

See Running Tests in Parallel for more information on how to use buildID with various continuous integration providers.

axe: {
  buildID: process.env.CI_BUILD_ID
}

configurationOverrides

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

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA',
    bestPractices: true
  }
}

elementInternals

(Optional) When true, Watcher gathers ARIA roles and properties set via the ElementInternals API from custom elements that use attachInternals(). This reduces false positives on pages that use custom elements for interactive components. Requires axe-core version 4.12.0 or later.

axe: {
  elementInternals: true
}

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/**' ]
}

In Exclude URLs from Analysis you can find a table of URLs and example patterns to verify matches.

git

(Optional) Controls how Watcher collects Git metadata for the current test run. Accepts one of three values:

• true (default): Watcher automatically collects Git information (branch, commit SHA, author, and other fields) using the local Git binary.
• false: Disables all Git metadata collection. Use this when running in environments without Git or when Git data collection is not needed.
• A GitConfig object: Provides explicit Git metadata and skips auto-detection entirely. Any fields you omit default to null. Use this when your tests run in a repository that is separate from the repository under test, or in CI environments where Git auto-detection is unreliable.

See Providing Git Metadata for more information.

The GitConfig object has the following fields:

branch, commitSha, and url are the gitful fields: a session submitted without all three is recorded as gitless and saved, but Axe Developer Hub switches to the gitless session view, where branch and commit history from previous sessions will not be visible. Submitting a subsequent session with all three fields restores the gitful view. If only one or two of the three are present, Axe Watcher drops all gitful fields, records the session as gitless, and includes a warning in the response.

Example using CI environment variables to supply explicit Git metadata:

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    url: process.env.GIT_URL,
    commitAuthor: process.env.GIT_AUTHOR_NAME,
    commitEmail: process.env.GIT_AUTHOR_EMAIL,
    commitMessage: process.env.GIT_COMMIT_MESSAGE,
    defaultBranch: 'main'
  }
}

projectId

(Required) Specifies the project ID that will receive the Watcher accessibility results. Your project ID is shown with the instructions when you create a new project, and you can also obtain it from the axe Developer Hub Projects Page .

axe: {
  projectId: process.env.AXE_PROJECT_ID
}

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 rule, rules, tag, or tags. The values property must be an array of strings representing the rule(s) or tag(s) 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 }
    }
  }
}

serverURL

(Optional) The URL of the Axe Developer Hub server to which Watcher sends accessibility results. Defaults to https://axe.deque.com.

You do not need to set this value if your project was created on axe.deque.com. However, if your organization uses a regional instance, private cloud, or on-premises deployment of Axe Developer Hub, set serverURL to the base URL of that instance:

axe: {
  apiKey: process.env.ACCESSIBILITY_API_KEY,
  projectId: process.env.PROJECT_ID,
  serverURL: process.env.SERVER_URL // e.g., 'https://axe-eu.deque.com'
}

sessionId

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

testingTypes

(Optional) The testingTypes property is an array of strings for use with Cypress to specify component or e2e (end-to-end) testing (or both).

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

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

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

cypressConfig Example

import { defineConfig } from 'cypress'
import { cypressConfig } from '@axe-core/watcher/cypress/config'

export default defineConfig(
  cypressConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightConfig

Creates a configuration for Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parameters

• opts: Configuration & LaunchOptions

  Intersection type of LaunchOptions and Configuration.

Returns: LaunchOptions

playwrightConfig Example

import { chromium } from 'playwright'
import { playwrightConfig } from '@axe-core/watcher/playwright'

const browserContext = await chromium.launchPersistentContext(
  '',
  playwrightConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

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

playwrightTest Example

// fixtures.ts
import { playwrightTest } from '@axe-core/watcher/playwright-test'

export default playwrightTest({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

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

puppeteerConfig Example

import puppeteer from 'puppeteer'
import { puppeteerConfig } from '@axe-core/watcher/puppeteer'

const browser = await puppeteer.launch(
  puppeteerConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

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

wdioConfig Example

import { remote } from 'webdriverio'
import { wdioConfig } from '@axe-core/watcher/wdio'

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    },
    capabilities: { browserName: 'chrome' }
  })
)

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

wdioTestRunner Example

import { wdioTestRunner } from '@axe-core/watcher/wdio'

export const config = wdioTestRunner({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

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

webdriverConfig Example

import { Builder } from 'selenium-webdriver'
import { Options } from 'selenium-webdriver/chrome'
import { webdriverConfig } from '@axe-core/watcher/webdriver'

const options = new Options()
const browser = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(
    webdriverConfig({
      axe: {
        apiKey: process.env.API_KEY,
        projectId: process.env.PROJECT_ID
      },
      options
    })
  )
  .build()

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 AxeConfiguration Interface section above 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.

accessibilityStandard

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'
• 'RGAAv4' - RGAA version 4 (French accessibility standard; requires axe-core 4.11.0 or later)

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

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA'
  }
}

axeCoreVersion

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.

axe: {
  configurationOverrides: {
    axeCoreVersion: 'latest'
  }
}

bestPractices

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.

axe: {
  configurationOverrides: {
    bestPractices: true
  }
}

experimentalRules

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.

axe: {
  configurationOverrides: {
    experimentalRules: true
  }
}

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 Example

await controller.analyze()

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 Example

await controller.flush()

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 Example

await controller.start()

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 Example

await controller.stop()

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

PlaywrightController Example

import { PlaywrightController, wrapPlaywrightPage } from '@axe-core/watcher/playwright'

let page = await browserContext.newPage()
const controller = new PlaywrightController(page)
page = wrapPlaywrightPage(page, controller)

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

PuppeteerController Example

import { PuppeteerController, wrapPuppeteerPage } from '@axe-core/watcher/puppeteer'

let page = await browser.newPage()
const controller = new PuppeteerController(page)
page = wrapPuppeteerPage(page, controller)

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

WdioController Example

import { WdioController, wrapWdio } from '@axe-core/watcher/wdio'

// browser is the WebdriverIO Browser instance from your wdioConfig() setup
const controller = new WdioController(browser)
wrapWdio(browser, controller)

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

WebdriverController Example

import { WebdriverController, wrapWebdriver } from '@axe-core/watcher/webdriver'

// browser is the Selenium WebDriver instance from your webdriverConfig() setup
const controller = new WebdriverController(browser)
browser = wrapWebdriver(browser, controller)

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/cypress/support')

// 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
}