Automate Accessibility Testing with Axe

This skill is an axe-core accessibility testing expert covering WCAG guidelines, axe-core implementation patterns, CI/CD integration, and issue remediation strategies. Core principles: a shift-left approach integrating accessibility testing early in development, multi-layered testing combining automated axe runs with manual testing, targeting WCAG 2.1 AA as the compliance baseline, generating developer-friendly reports, and continuous regression monitoring.

Use it when accessibility testing needs to be wired into an actual test suite or CI pipeline - browser tests, component tests, or end-to-end flows - rather than a one-off manual audit.

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

test('homepage accessibility', async ({ page }) => {
  await page.goto('https://example.com');
  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze();
  expect(accessibilityScanResults.violations).toEqual([]);
});

Implementation patterns are shown across five integration points: Playwright browser tests via AxeBuilder, Jest + jsdom component tests via jest-axe's toHaveNoViolations matcher, a shared custom axe configuration (enabling/disabling specific rules, tag sets, locale, pinned axe version), Python Selenium via axe-selenium-python, and a GitHub Actions workflow running npm run test:a11y and uploading a JSON report artifact on failure. A custom AccessibilityReporter class is shown generating a structured violation report (summary, WCAG level, per-violation impact/description/help/affected nodes) and deciding whether a build should fail based on critical/serious-impact violations. Storybook integration uses injectAxe/checkA11y in a test-runner's pre/post-render hooks. Best practices cover test organization (group by user journey, test interactive and dynamic states, test in realistic page contexts), performance optimization (scope rules and excludes for CI speed), a five-step violation remediation workflow (prioritize by severity, document legitimate exceptions via rule config, create tickets linked to WCAG success criteria, verify fixes, monitor for regressions), and handling false positives by scoping specific rules like color-contrast or button-name to exclude legitimate exceptions rather than disabling them globally.

The GitHub Actions workflow triggers on both push and pull-request events, installs with npm ci on Node 18 via actions/setup-node@v4, runs npm run test:a11y, and uploads the accessibility report as a build artifact only when the job fails.

Frontend developers and QA engineers who need to wire automated WCAG-level accessibility testing into their actual test suite and CI pipeline - not just run a one-time browser extension scan - across whichever framework (Playwright, Jest, Selenium, Storybook) their stack already uses. Testing dynamic content is treated as its own concern: the skill includes a worked example of scanning a modal only after it's fully rendered and visible, then separately verifying that keyboard focus correctly lands on the modal's close button, since accessibility issues in interactive, post-render UI states are exactly what a static-page scan misses.