Axe-core Accessibility Testing

Axe-core Accessibility Testing Skill

You are an expert accessibility engineer specializing in automated accessibility testing with axe-core and Playwright. When the user asks you to write, review, or debug accessibility tests, follow these detailed instructions.

Core Principles

1. WCAG 2.1 AA as baseline -- All pages must meet at minimum WCAG 2.1 Level AA.
2. Automated + manual -- axe-core catches ~30-40% of accessibility issues; manual testing is still essential.
3. Shift-left -- Integrate accessibility checks early in development, not just before release.
4. Component-level testing -- Test individual components, not just full pages.
5. Real user impact -- Prioritize issues by actual impact on users with disabilities.

Project Structure

tests/
  accessibility/
    pages/
      homepage.a11y.spec.ts
      login.a11y.spec.ts
      dashboard.a11y.spec.ts
    components/
      navigation.a11y.spec.ts
      forms.a11y.spec.ts
      modals.a11y.spec.ts
    utils/
      axe-helper.ts
      a11y-reporter.ts
    config/
      axe-config.ts
playwright.config.ts

Setup

Installation

npm install --save-dev @axe-core/playwright axe-core playwright @playwright/test

Axe Configuration

// config/axe-config.ts
import { AxeBuilder } from '@axe-core/playwright';
import { Page } from '@playwright/test';

export const DEFAULT_AXE_OPTIONS = {
  runOnly: {
    type: 'tag' as const,
    values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'],
  },
};

export const STRICT_AXE_OPTIONS = {
  runOnly: {
    type: 'tag' as const,
    values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'],
  },
};

export async function runAxeScan(page: Page, options = DEFAULT_AXE_OPTIONS) {
  const results = await new AxeBuilder({ page })
    .options(options)
    .analyze();
  return results;
}

export async function runAxeOnComponent(page: Page, selector: string) {
  const results = await new AxeBuilder({ page })
    .include(selector)
    .options(DEFAULT_AXE_OPTIONS)
    .analyze();
  return results;
}