@a11y-tools/pw-a11y

Plug-and-play accessibility testing for Playwright. Add automated accessibility checks to your existing Playwright tests without modifying any test files.

Features

• Zero config required - Works with your existing Playwright setup
• No test modifications - Automatically scans after each test
• Rich HTML reports - Results attached to Playwright's built-in HTML reporter
• Powered by axe-core - Industry-standard accessibility engine
• Configurable - Control behavior via environment variables

Installation

npm install -D @a11y-tools/pw-a11y

Quick Start

Instead of running:

npx playwright test

Run:

npx pw-a11y test

That's it! Your tests will now include automatic accessibility scans with results attached to the HTML report.

Usage

Basic Usage

# Run all tests with a11y scanning
npx pw-a11y test

# Run specific test file
npx pw-a11y test tests/homepage.spec.js

# Run with headed browser
npx pw-a11y test --headed

# All Playwright arguments work as expected
npx pw-a11y test --project=chromium --workers=4

Viewing Results

After running tests, open the Playwright HTML report:

npx playwright show-report

Each test will have accessibility attachments:

• accessibility-report.html - Visual HTML report with violation details
• accessibility-results.json - Full axe-core results for programmatic access
• accessibility-summary.txt - Plain text summary

Configuration

Control behavior with environment variables:

| Variable | Default | Description | |----------|---------|-------------| | PW_A11Y | 1 | Enable/disable a11y scanning (1 or 0) | | PW_A11Y_FAIL | 0 | Fail tests on violations (1 or 0) | | PW_A11Y_TAGS | (all) | Comma-separated axe rule tags (e.g., wcag2a,wcag2aa) | | PW_A11Y_TIMEOUT_MS | 0 | Wait time in ms before scanning | | PW_A11Y_EXCLUDE | (none) | CSS selectors to exclude from scan | | PW_A11Y_INCLUDE | (all) | CSS selectors to include in scan |

Examples

# Fail tests on any accessibility violation
PW_A11Y_FAIL=1 npx pw-a11y test

# Only check WCAG 2.1 AA rules
PW_A11Y_TAGS=wcag21aa npx pw-a11y test

# Exclude specific elements
PW_A11Y_EXCLUDE=".third-party-widget,.ad-banner" npx pw-a11y test

# Wait for animations before scanning
PW_A11Y_TIMEOUT_MS=500 npx pw-a11y test

# Disable scanning for specific run
PW_A11Y=0 npx pw-a11y test

Common WCAG Tag Combinations

# WCAG 2.0 Level A only
PW_A11Y_TAGS=wcag2a

# WCAG 2.0 Level AA (includes Level A)
PW_A11Y_TAGS=wcag2a,wcag2aa

# WCAG 2.1 Level AA
PW_A11Y_TAGS=wcag2a,wcag2aa,wcag21aa

# Best practices (non-WCAG)
PW_A11Y_TAGS=best-practice

How It Works

1. CLI Wrapper - pw-a11y wraps the Playwright test runner
2. Fixture Injection - Intercepts @playwright/test imports to extend the page fixture
3. Automatic Scanning - After each test, axe-core scans the current page state
4. Report Attachments - Results are attached to Playwright's HTML report

No modifications to your test files are required because the package hooks into Node's module system to provide extended fixtures.

Report Example

The HTML attachment shows:

• Summary statistics (violations, passes, incomplete)
• Violations grouped by impact level (critical, serious, moderate, minor)
• Affected elements with CSS selectors
• Links to axe-core documentation for each rule

CI/CD Integration

GitHub Actions

- name: Run accessibility tests
  run: npx pw-a11y test
  env:
    PW_A11Y_FAIL: 1  # Fail pipeline on violations

- name: Upload report
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: playwright-report
    path: playwright-report/

Fail on Critical/Serious Only

For gradual adoption, you can review results without failing the build:

- name: Run tests (report only)
  run: npx pw-a11y test
  # PW_A11Y_FAIL defaults to 0

Troubleshooting

Tests pass but no a11y results

Ensure PW_A11Y=1 (this is the default when using npx pw-a11y).

Scan errors on blank pages

The scanner skips about:blank and error pages automatically.

Third-party content causing violations

Exclude third-party widgets:

PW_A11Y_EXCLUDE=".third-party-iframe,.external-widget" npx pw-a11y test

TypeScript projects

The package works with TypeScript Playwright projects. The fixture injection happens at runtime.

Requirements

• Node.js >= 18
• @playwright/test >= 1.40.0

License

MIT