axe-audit

Accessibility audit CLI powered by axe-core and Playwright. Automatically checks WCAG compliance of your static site with no configuration required.

日本語

Features

• No configuration required — Works out of the box with sensible defaults
• Automatic page discovery — Recursively scans build output for HTML files
• 18 languages — axe-core messages in 18 locales (default: Japanese)
• Multiple output formats — HTML (browser) / JSON / CSV
• Package manager auto-detection — Detects npm / yarn / pnpm / bun from lock files
• Page exclusion — Exclude pages by glob patterns (e.g. CMS-generated pages)
• CI/CD ready — Auto-detects CI environments, exit codes for pipeline integration

Installation

npm install -D axe-audit
npx playwright install chromium

Quick Start

1. Generate a config file (optional)

npx axe-audit init

Creates axe-audit.config.mjs in your project root.

2. Run the audit

npx axe-audit

Build → page discovery → accessibility testing → report display runs automatically.

CLI Reference

Commands

| Command | Description | | --- | --- | | axe-audit | Run accessibility audit | | axe-audit init | Generate config file axe-audit.config.mjs |

Flags

| Flag | Description | | --- | --- | | --no-build | Skip the build step | | --json | Output JSON report (axe-audit/report.json) | | --csv | Output CSV report (axe-audit/report.csv) | | --help | Show help | | --version | Show version |

Configuration

All options for axe-audit.config.mjs generated by axe-audit init:

// @ts-check
import { defineConfig } from "axe-audit";

export default defineConfig({
  dist: "dist",
  buildCommand: undefined,
  noBuild: false,
  port: 3000,
  json: false,
  csv: false,
  showIncomplete: false,
  showPasses: false,
  showInapplicable: false,
  excludePages: [],
  axe: {
    tags: undefined,
    locale: "ja",
    aaa: false,
    experimental: false,
    disableRules: [],
    include: [],
    exclude: [],
  },
});

Top-Level Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | dist | string | "dist" | Build output directory | | buildCommand | string | undefined | Custom build command. Auto-detects PM when unset | | noBuild | boolean | false | Skip the build step | | port | number | 3000 | Local server port | | json | boolean | false | Output JSON report | | csv | boolean | false | Output CSV report | | showIncomplete | boolean | false | Show incomplete (needs review) rules in HTML report | | showPasses | boolean | false | Show passing rules in HTML report | | showInapplicable | boolean | false | Show inapplicable rules in HTML report | | excludePages | string[] | [] | Glob patterns to exclude pages (e.g. ["**/interview/*/*", "404.html"]) |

excludePages Patterns

Uses glob syntax to match page paths relative to dist/.

| Pattern | Matches | Does NOT match | | --- | --- | --- | | **/interview/*/* | saiyo/interview/01/index.html | saiyo/interview/index.html | | **/draft/** | blog/draft/post.html | blog/post.html | | 404.html | 404.html | about/404.html |

Supported wildcards: ** (any directory depth), * (any characters except /), ? (single character).

axe Sub-Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | tags | string[] | undefined | Filter rules by tag (e.g. ["wcag2a", "wcag2aa"]). All rules enabled when unset | | locale | string | "ja" | Language for axe-core messages. Set to undefined for English | | aaa | boolean | false | Include WCAG AAA level tests | | experimental | boolean | false | Include experimental rules | | disableRules | string[] | [] | Rule IDs to disable (e.g. ["color-contrast"]) | | include | string[] | [] | CSS selectors to audit. Empty array for entire page | | exclude | string[] | [] | CSS selectors to exclude (e.g. [".third-party", "iframe"]) |

Output Formats

HTML (default)

A custom HTML report is generated (axe-audit/report.html) and opens automatically in your browser via a local HTTP server. On macOS, Google Chrome is used if installed; otherwise the default browser is used. Skipped in CI environments.

The report includes audited pages and excluded pages sections at the bottom, showing which pages were tested and which were excluded by excludePages patterns.

JSON

Enable with the --json flag or json: true in config. Outputs axe-audit/report.json.

{
  "metadata": {
    "axeVersion": "4.10.0",
    "timestamp": "2025-01-01T00:00:00.000Z",
    "toolVersion": "1.1.0",
    "auditedPages": ["/", "/about/", "/contact/"],
    "excludedPages": ["/admin/", "/draft/"]  // only present when excludePages is set
  },
  "pages": [
    {
      "url": "/",
      "violations": [
        {
          "id": "color-contrast",
          "impact": "serious",
          "tags": ["wcag2aa"],
          "description": "...",
          "help": "...",
          "helpUrl": "...",
          "nodes": [
            {
              "html": "<p style=\"color: #aaa\">...</p>",
              "target": ["p:nth-child(2)"],
              "failureSummary": "..."
            }
          ]
        }
      ],
      "incomplete": [],
      "passes": [],
      "inapplicable": []
    }
  ],
  "summary": {
    "totalPages": 3,
    "totalViolations": 1,
    "totalIncomplete": 0,
    "pagesWithViolations": 1,
    "pagesWithErrors": 0
  }
}

CSV

Enable with the --csv flag or csv: true in config. Outputs axe-audit/report.csv (UTF-8 with BOM for Excel compatibility).

| Column | Description | | --- | --- | | page | URL of the audited page | | type | Result type (violations / incomplete / passes / inapplicable) | | impact | Severity (critical / serious / moderate / minor) | | ruleId | Rule ID | | help | Help text | | html | HTML snippet of the target element | | target | CSS selector(s) of the target element | | failureSummary | Specific failure reason | | wcag | Applicable WCAG criteria | | helpUrl | URL to detailed help |

Supported Locales

axe-core messages can be displayed in 18 languages. Set the language code in axe.locale.

| Code | Language | | --- | --- | | da | Danish | | de | German | | el | Greek | | es | Spanish | | eu | Basque | | fr | French | | he | Hebrew | | it | Italian | | ja | Japanese (default) | | ko | Korean | | nl | Dutch | | no_NB | Norwegian Bokmål | | pl | Polish | | pt_BR | Portuguese (Brazil) | | pt_PT | Portuguese (Portugal) | | ru | Russian | | zh_CN | Chinese (Simplified) | | zh_TW | Chinese (Traditional) |

For English, set locale to undefined or omit the key.

License

MIT