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

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

### Axe Configuration

```typescript
// 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;
}
```

## Writing Accessibility Tests

### Full Page Scan

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

test.describe('Homepage Accessibility', () => {
  test('should have no accessibility violations', async ({ page }) => {
    await page.goto('/');

    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
      .analyze();

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

  test('should have no critical or serious violations', async ({ page }) => {
    await page.goto('/');

    const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

    const criticalViolations = accessibilityScanResults.violations.filter(
      (v) => v.impact === 'critical' || v.impact === 'serious'
    );

    expect(criticalViolations).toEqual([]);
  });

  test('should pass accessibility after dynamic content loads', async ({ page }) => {
    await page.goto('/');

    // Wait for dynamic content
    await page.getByRole('heading', { name: 'Featured Products' }).waitFor();
    await page.waitForLoadState('networkidle');

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });
});
```

### Component-Level Scanning

```typescript
test.describe('Navigation Component Accessibility', () => {
  test('navigation menu should be accessible', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .include('nav[aria-label="Main navigation"]')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

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

  test('navigation should have proper ARIA landmarks', async ({ page }) => {
    await page.goto('/');

    // Check for main navigation landmark
    const nav = page.getByRole('navigation', { name: 'Main navigation' });
    await expect(nav).toBeVisible();

    // Check for skip navigation link
    const skipLink = page.getByRole('link', { name: /skip to/i });
    await expect(skipLink).toBeAttached();
  });

  test('mobile menu should be accessible when opened', async ({ page }) => {
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto('/');

    // Open mobile menu
    const menuButton = page.getByRole('button', { name: /menu/i });
    await menuButton.click();

    // Scan the opened menu
    const results = await new AxeBuilder({ page })
      .include('[role="dialog"], [aria-expanded="true"]')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

    expect(results.violations).toEqual([]);

    // Verify focus management
    const firstMenuItem = page.getByRole('menuitem').first();
    await expect(firstMenuItem).toBeFocused();
  });
});
```

### Form Accessibility

```typescript
test.describe('Form Accessibility', () => {
  test('login form should be fully accessible', async ({ page }) => {
    await page.goto('/login');

    const results = await new AxeBuilder({ page })
      .include('form')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

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

  test('form inputs should have associated labels', async ({ page }) => {
    await page.goto('/login');

    // Every input should be findable by its label
    await expect(page.getByLabel('Email')).toBeVisible();
    await expect(page.getByLabel('Password')).toBeVisible();
  });

  test('form errors should be announced to screen readers', async ({ page }) => {
    await page.goto('/login');

    // Submit empty form
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Error messages should have appropriate ARIA attributes
    const errorMessages = page.locator('[role="alert"]');
    await expect(errorMessages.first()).toBeVisible();

    /