a11y-agent

Accessibility testing CLI — crawls a website and reports WCAG violations using axe-core and Playwright.

Features

• Crawls up to N pages via sitemap or link discovery
• Tests each page against WCAG 2.2 AA (or 2.1 AA / 2.0 AA)
• Reports violations by impact: critical, serious, moderate, minor
• Flags items that need manual review
• Outputs HTML, CSV, and JSON reports

Requirements

• Node.js 18+

Installation

npm install -g @mraichelson/a11y-agent

After installing, run the Playwright browser setup once:

a11y-agent --install-browsers
# or
npx playwright install chromium

Usage

a11y-agent <url> [options]

Arguments

| Argument | Description | |----------|-------------| | <url> | Base URL to scan (must include http:// or https://) |

Options

| Flag | Default | Description | |------|---------|-------------| | -s, --standard <standard> | wcag22aa | WCAG standard: wcag22aa, wcag21aa, or wcag2aa | | -m, --max-pages <number> | 20 | Maximum number of pages to scan | | -t, --timeout <ms> | 30000 | Per-page load timeout in milliseconds | | -o, --output-dir <dir> | ./a11y-reports | Directory where report files are saved | | --include <pattern> | | Only test URLs whose path matches (repeatable, supports * and **) | | --exclude <pattern> | | Skip URLs whose path matches (repeatable, supports * and **) |

Examples

Scan a site with default settings:

a11y-agent https://example.com

Scan against WCAG 2.1 AA, up to 50 pages:

a11y-agent https://example.com --standard wcag21aa --max-pages 50

Only scan blog posts:

a11y-agent https://example.com --include '/blog/**'

Skip the checkout flow:

a11y-agent https://example.com --exclude '/checkout/**'

Combine include and exclude filters:

a11y-agent https://example.com --include '/products/**' --exclude '/products/*/reviews'

Save reports to a custom directory:

a11y-agent https://example.com --output-dir ./reports/audit-2024

How it works

1. Discovery — checks for a /sitemap.xml first; if none is found, crawls links from the root page. Sitemap origin mismatches (e.g. production URLs in a local sitemap) are automatically rewritten to the base origin.
2. Testing — each discovered URL is loaded in a headless Chromium browser and tested with axe-core.
3. Reporting — results are printed to the terminal and saved as HTML, CSV, and JSON files.

Reports

Three files are written to the output directory after each scan:

| File | Description | |------|-------------| | a11y-report.html | Interactive report with expandable violations per page | | a11y-report.csv | Spreadsheet-friendly format with Status and Notes columns for tracking remediation | | a11y-report.json | Full structured data for programmatic use |

Exit codes

| Code | Meaning | |------|---------| | 0 | No violations found | | 1 | One or more violations found | | 2 | Invalid arguments or fatal error |

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run from source (no build step)
npm run dev -- https://example.com

# Release (requires release-it config)
npm run release

License

ISC