Generate Reports

When you use the Axe DevTools APIs or the axe CLI to test for accessibility, results are saved as JSON files. Use the axe reporter command to convert those JSON files into HTML, JUnit XML, CSV, or universal format reports. You can also filter results by type before generating a report.

• The axe reporter Command
• Options
• JSON Results on Disk

The axe reporter Command

axe reporter <results-dir> [dest-dir] [options]

The <results-dir> is the directory containing JSON result files. The optional [dest-dir] is where reports are written; you can also use --dest to specify it.

Generate a CSV report from JSON results:

axe reporter ./axe-results/ ./axe-reports/csv/ --format=csv

Generate reports in multiple formats at once:

axe reporter ./axe-results/ ./axe-reports/ --format=csv,html,junit

Options

-d, --dest <path>

Specifies the output directory for generated reports. You can instead specify the destination as the second positional argument.

-f, --format <type(s)>

Output format(s): html, junit (XML), csv, or universal. To generate multiple formats in one run, provide them separated by commas, spaces, semicolons, or plus signs. Spacing around separators is ignored.

The universal value outputs a JSON file in the Axe Universal Format, which is a standard schema shared across Axe products. Use the companion options below to control what metadata is recorded in the output.

--universal-ruleset <id>

Specifies the ruleset ID to record in the metadata of the universal format output. Defaults to wcag2.1. See the ruleset table for valid values.

--universal-best-practices

Records bestPracticesEnabled=true in the metadata of the universal format output.

HTML Reports

An HTML report renders itself when you open it. Before writing the file, the CLI also tries to pre-render it into static markup, so its content is already there and displays as soon as you open it, instead of a moment later. This step is unrelated to the browser you used for testing, so options like --chrome-path and --chrome-options don't apply here.

If you installed the CLI as a Node.js package, pre-rendering works automatically and no browser is needed. If you're using the standalone executable, the CLI instead looks for an installed Chrome, Edge, or Brave to use for this step. To point it at a specific browser, set the AXE_DEVTOOLS_REPORTER_BROWSER_PATH environment variable.

If the CLI finds no browser (when using the standalone executable), it prints a warning and still writes the report. The report still displays and works normally when you open it, just without that instant-display optimization.

On a slow build machine or with a large report, generating an HTML report can fail with an error such as browser render timed out after 30000ms. To allow more time, set AXE_DEVTOOLS_REPORTER_RENDER_TIMEOUT_MS to a number of milliseconds. The default is 30000 (30 seconds). Write the value as plain digits; any other value is ignored and the default is used.

export AXE_DEVTOOLS_REPORTER_RENDER_TIMEOUT_MS=120000

For the other environment variables that control how HTML reports are generated, see Pre-rendering HTML reports.

--filter <type(s)>

Filters which result types to include in the report. Accepts one or more of: passes, violations, incomplete, inapplicable. Separate multiple values with commas and no spaces. Requires --format csv.

# Include only violations and incomplete results
axe reporter ./axe-results/ --format=csv --filter violations,incomplete

# Include only passed checks
axe reporter ./axe-results/ --format=csv --filter passes

-b, --browser <name>

When a results directory contains results from multiple browsers, use this option to generate a report from only one browser's results. The name should match the browser used when running tests, for example, chrome or firefox.

JSON Results on Disk

Understanding how the Axe DevTools CLI names and organizes JSON result files is useful when working with the axe reporter command or processing results programmatically.

Directory Structure

For each project in a spec file, results are saved in a subdirectory named after the project's id, inside the output directory you specify:

<output-dir>/<project-id>/

This subdirectory is created automatically. If it already exists from a previous run, it is archived by renaming it to <project-id>-<timestamp> before a fresh directory is created.

File Naming

Each JSON result file is named using the project id and a page state derived from the page id and the optional title from the analyze action:

<project-id>-<page-id>[-<analyze-title>].json

The page id comes from the id field in pageList. If id is not explicitly set on a page, it is derived automatically from the page name by removing spaces.

The analyze-title segment is appended only when a title is provided in the analyze action, or when a page has multiple analyze calls (in which case each result gets a unique suffix to avoid collisions).

Example

Given a project with id: "deque" and a page with name: "Deque search" (no explicit id), the auto-derived page ID is Dequesearch. A single analyze call with no title produces:

<output-dir>/deque/deque-Dequesearch.json

With analyze the page with title "initial state":

<output-dir>/deque/deque-Dequesearch-initial state.json