Overview of the Java Watcher APIs

The Axe Watcher Java integration provides a comprehensive SDK for adding automated accessibility testing to Selenium Java test suites. This integration automatically analyzes web pages for accessibility issues and sends results to the Axe Developer Hub for tracking and analysis.

Core Components

Main Classes

AxeWatcher - The primary entry point for the integration. This class handles the configuration of browser options and wrapping of WebDriver instances to enable accessibility testing.

AxeWatcherOptions - Configuration class that defines how axe Watcher operates, including API keys, server URLs, build IDs for parallel testing, and various testing behaviors.

ConfigurationOverrides - Allows overriding global accessibility configuration settings, including accessibility standards (WCAG 2.1 AA, WCAG 2.2 AA, etc.), best practices, and experimental rules.

Driver Integration

AxeWatcherDriver - Interface that extends the standard Selenium WebDriver to provide access to accessibility testing functionality through the axeWatcher() method.

AxeWatcherController - Provides fine-grained control over when and how accessibility analysis occurs, with methods to start, stop, analyze, and flush test results.

Configuration Classes

Runtime Options

AxeRunOptions - Controls advanced runtime behavior of the axe-core engine, including rule configurations and ancestry information for violations.

AxeRunOnly - Limits which accessibility rules are executed by specifying rule IDs or tags (e.g., "wcag21aa", "best-practice").

AxeRunContext - Defines the scope of testing by including or excluding specific DOM elements using CSS selectors.

AxeRuleOptions - Enables or disables individual accessibility rules by rule ID.

Usage

Basic Setup

// Configure options
AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("API_KEY") // Required. Secret stored in an environment variable.

// Create watcher and configure Chrome
AxeWatcher watcher = new AxeWatcher(options);
ChromeOptions chromeOptions = watcher.configure(new ChromeOptions());
ChromeDriver chromeDriver = new ChromeDriver(chromeOptions);

// Wrap driver for accessibility testing
WebDriver driver = watcher.wrapDriver(chromeDriver);

// Access the controller for manual control
AxeWatcherController controller = ((AxeWatcherDriver) driver).axeWatcher();

Advanced Configuration

Custom Accessibility Standards

ConfigurationOverrides overrides = new ConfigurationOverrides()
    .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
    .setEnableBestPractices(true)
    .setEnableExperimental(false);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("API_KEY") // Required. Secret stored in an environment variable.
    .setConfigurationOverrides(overrides);

Selective Rule Execution

// Run only specific accessibility tags
AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa", "best-practice"));

AxeRunOptions runOptions = new AxeRunOptions()
    .setRunOnly(runOnly)
    .setAncestry(true);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("API_KEY") // Required. Secret stored in an environment variable.
    .setRunOptions(runOptions);

Scoped Testing

// Include only specific elements
AxeRunContext context = new AxeRunContext()
    .setInclude(Arrays.asList("#main-content", ".form-section"))
    .setExclude(Arrays.asList("#header", "#footer"));

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("API_KEY") // Required. Secret stored in an environment variable.
    .setRunContext(context);

Important Constraints

1. Mutually Exclusive Options: Cannot use both ConfigurationOverrides.accessibilityStandard and AxeRunOptions.runOnly simultaneously
2. Browser Limitations: Does not support full headless mode or incognito mode
3. Method Order: Must call configure() before creating ChromeDriver, and wrapDriver() after
4. Result Flushing: Always call controller.flush() in test teardown to ensure results are sent to Axe Developer Hub
5. Frame Limitations: Controller methods don't work within iframes or on non-HTTP(S) pages

This integration offers both automatic and manual testing modes, enabling teams to seamlessly integrate comprehensive accessibility testing into existing Selenium Java test suites with minimal code changes.