Capture Violation Screenshots

When Axe Watcher finds accessibility violations, it can capture a screenshot of the page at that moment. Screenshots are uploaded to Axe Developer Hub so you can see what the page looked like when the violation was recorded, and optionally saved to a local directory for inspection during development.

Screenshot capture is available for all JavaScript and TypeScript integrations (Playwright Test, Cypress, WebdriverIO, and Puppeteer) and both Java integrations (Selenium and Playwright).

Enable Screenshot Capture

JavaScript or TypeScript:

Set takeScreenshots: true in your AxeConfiguration:

axe: {
  takeScreenshots: true
}

Java:

Call setTakeScreenshots(true) on AxeWatcherOptions:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setTakeScreenshots(true);

Screenshots are uploaded to Axe Developer Hub automatically. No additional configuration is required to view them there.

Save Screenshots Locally

You can also save screenshots to a directory on your local machine. This is useful for reviewing violations while tests are running locally, without opening Axe Developer Hub.

JavaScript or TypeScript:

Add screenshotDir to your AxeConfiguration:

axe: {
  takeScreenshots: true,
  screenshotDir: './axe-screenshots'
}

Java:

Call setScreenshotDir() on AxeWatcherOptions:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setTakeScreenshots(true)
    .setScreenshotDir("./axe-screenshots");

setScreenshotDir has no effect unless setTakeScreenshots(true) is also set. Relative paths are resolved against the JVM working directory. If the directory does not exist, Watcher creates it. If directory creation or file writing fails, a warning is logged and the test suite continues.

Screenshots are written using this filename pattern: YYYYMMDDTHHmmssSSS-{id}.png. The timestamp prefix keeps files sorted by capture time and prevents collisions when multiple screenshots are taken in the same test run.

See setTakeScreenshots and setScreenshotDir in the Java API reference for full parameter details.