Get Started with Axe Watcher

This guide walks you through setting up Axe Watcher to add automated accessibility testing to your existing end-to-end test suite.

Understanding Watcher and Axe Developer Hub

Axe Watcher is an input source for Axe Developer Hub that you integrate into your test suite, while Axe Developer Hub is the web platform where you view and manage your accessibility results. They work together as a complete accessibility testing solution:

Axe Watcher runs with your automated tests, analyzing each page your tests visit for accessibility issues. It detects DOM changes and captures multiple page states, making it ideal for testing dynamic content like single-page applications, login flows, and interactive components. When integrated with Git, Watcher associates results with specific commits and branches.

Axe Developer Hub receives accessibility results from input sources such as Watcher and presents them in an organized interface. You can track accessibility issues across commits, compare branches, filter by severity, and monitor your project's accessibility progress over time. The platform de-duplicates issues, so you see each unique problem once.

Setup Steps

1. Create a Watcher Project

A project in Axe Developer Hub holds your accessibility results, test run information, and Git data. Each project has a unique project ID that links your test runs to it.

To create a project:

1. Visit the Axe Developer Hub Startup page  or click Add new project from your Projects page.
2. Choose Axe Watcher from the Choose Your Integration Method page.
3. Name your project.
4. Select your programming language.
5. Choose your browser automation platform.

For complete instructions, see Set Up Projects.

2. Modify Your Test Suite

Integrating Watcher requires minimal changes to your existing tests. The general process involves:

1. Installing the Watcher package
2. Importing the configuration functions and controller classes
3. Wrapping your browser configuration with Watcher's config function
4. Wrapping your browser or page instance with Watcher
5. Flushing your results after each test to send results to Axe Developer Hub

The specific implementation varies by platform. Choose your language from the links below to be directed to instructions specific to your browser automation platform:

• JavaScript
• TypeScript
• Java

If you don't have an existing test suite to modify, the Axe Watcher Examples repository provides working examples for each supported platform.

3. Run Your Tests and Check Results

Once you've modified your test suite, run it as you normally would. Watcher automatically analyzes pages and sends results to Axe Developer Hub.

After the test run completes, visit your project in axe Developer Hub to review the results. You'll see:

• Branches page (Git projects): Shows all scanned branches with accessibility summaries.
• Commits page (Git projects): Shows commits within a branch with comparison data.
• Test Runs page (non-Git projects): Shows each test run with timestamps and issue counts.
• Summary page: Displays all accessibility rules violated with issue counts by impact.
• Details page: Provides in-depth information about each violation, including the element location, source code, and remediation guidance.

For guidance on navigating your results, see Understand Results.

Next Steps

• Automate accessibility checks in CI/CD: Use the GitHub Action to block pull requests with accessibility errors, or integrate with other platforms using the REST service
• Customize your testing: Learn about manual mode to control which pages are analyzed
• Configure thresholds: Set up the a11y threshold to define your organization's tolerance for accessibility errors
• Use a global configuration: Apply consistent accessibility standards across your organization