axe-a11y

Overview

axe-core is "an accessibility testing engine for websites and other HTML-based user interfaces" maintained by Deque (axe-core). It identifies approximately 57% of WCAG issues automatically and flags items requiring human review as "incomplete" (axe-core).

The integration shape: load the engine into a page (via test fixture, browser extension, or framework adapter), call axe.run(), and parse the violations[] array.

When to use

• The project ships JavaScript / TypeScript UI tests (Playwright / Cypress / Jest / Vitest).
• Automated a11y coverage on every PR is a goal.
• The team values WCAG SC tagging - axe rules map cleanly to WCAG 2.0 / 2.1 / 2.2 SCs.
• Pair with a11y-violation-gate for the ratchet pattern over baseline.

If the team is on a non-JS stack, evaluate pa11y-a11y (CLI; uses axe-core under the hood), lighthouse-a11y (CI-friendly, broader perf + a11y), or ibm-equal-access-a11y.

Install

npm install --save-dev axe-core

(Per axe-core.)

For framework integration (preferred over raw axe.run()):

Authoring scans

Raw axe.run() API

import axe from 'axe-core';

axe.run()
  .then(results => {
    if (results.violations.length) {
      console.error('a11y violations:', results.violations);
    }
  })
  .catch(err => {
    console.error('axe error:', err.message);
  });

(Adapted from axe-core.)

For test environments where loading axe via <script> is easier:

<script src="node_modules/axe-core/axe.min.js"></script>

Playwright integration

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('checkout page passes axe scan', async ({ page }) => {
  await page.goto('/checkout');

  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])     // limit to AA
    .analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

Cypress integration

// cypress/support/commands.js
import 'cypress-axe';

// In a test
cy.visit('/checkout');
cy.injectAxe();
cy.checkA11y();

Results structure

axe.run() resolves to an object with four arrays (axe-core):

Each violation has:

Triage with jq:

# Top violations by impact
jq -r '.violations[] | "\(.impact): \(.id) — \(.description)"' axe-results.json

# Just the failing selectors per rule
jq -r '.violations[] | "\(.id):", (.nodes[].target | tostring)' axe-results.json

Rule configuration

By tags

axe ships rules tagged with conformance levels:

new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])

Common tag sets:

Disable specific rules

new AxeBuilder({ page }).disableRules(['color-contrast'])

For per-page disabling (e.g. a known false positive on a specific component):

new AxeBuilder({ page })
  .exclude('.legacy-component')   // selector exclusion
  .analyze();

For per-rule severity in CI gating (e.g. block on critical / serious only): handle in a11y-violation-gate using the impact field.

CI integration

# .github/workflows/a11y.yml
name: a11y

on:
  pull_request:
  push:
    branches: [main]

jobs:
  axe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx playwright install --with-deps

      - name: Run a11y tests
        run: npx playwright test tests/a11y/

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: a11y-results
          path: playwright-report/
          retention-days: 14

For richer reporting, persist the raw accessibilityScanResults JSON as a build artifact and pipe to a11y-violation-gate.

Anti-patterns

Limitations

• Catches ~57% of WCAG issues (axe-core) - the rest require manual screen-reader testing (per screen-reader-test-author).
• Rule false positives. Rare but real; disableRules / exclude are escape hatches with documented rationale.
• Doesn't cover dynamic state changes well. A modal that opens after user interaction won't be scanned unless the test triggers the open before calling axe.run().

References

• axe-core - main repo: install, axe.run(), results structure.
• Deque rule documentation - https://dequeuniversity.com/rules/axe/
• @axe-core/playwright - https://github.com/dequelabs/axe-core-npm/tree/master/packages/playwright
• W3C WCAG 2.2 - https://www.w3.org/TR/WCAG22/
• a11y-violation-gate - CI gate using axe results.
• pa11y-a11y, lighthouse-a11y, wave-a11y, ibm-equal-access-a11y - alternative scanners.