npm install -D @axe-core/playwright axe-core

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

test.describe('Accessibility', () => {
  test('homepage has no WCAG 2.1 AA violations', async ({ page }) => {
    await page.goto('/');

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

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

  test('login page is accessible', async ({ page }) => {
    await page.goto('/login');

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

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

// Scoped to a specific region
test('navigation is accessible', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .include('[role="navigation"]')
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

// After interaction (modals, dropdowns)
test('modal is accessible after opening', async ({ page }) => {
  await page.goto('/dashboard');
  await page.getByRole('button', { name: 'Settings' }).click();
  await page.waitForSelector('[role="dialog"]');

  const results = await new AxeBuilder({ page })
    .include('[role="dialog"]')
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

// Disable specific rules when justified
const results = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa'])
  .disableRules(['color-contrast'])
  .options({ rules: { 'region': { enabled: true } } })
  .analyze();

// Detailed violation logging
if (results.violations.length > 0) {
  const report = results.violations.map((v) => ({
    rule: v.id, impact: v.impact, description: v.description,
    helpUrl: v.helpUrl,
    nodes: v.nodes.map((n) => ({ html: n.html, target: n.target, failureSummary: n.failureSummary })),
  }));
  console.error('A11y violations:', JSON.stringify(report, null, 2));
}

npm install -D jest-axe @types/jest-axe

import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

describe('Button component', () => {
  it('should have no accessibility violations', async () => {
    const { container } = render(
      <button type="button" aria-label="Close dialog">X</button>
    );
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

npm install -D pa11y pa11y-ci

# Single page audit
npx pa11y --standard WCAG2AA https://example.com

# JSON output for CI
npx pa11y --reporter json https://example.com > a11y-report.json

// .pa11yci.json
{
  "defaults": {
    "standard": "WCAG2AA",
    "timeout": 30000,
    "chromeLaunchConfig": { "args": ["--no-sandbox"] }
  },
  "urls": [
    "http://localhost:3000/",
    "http://localhost:3000/login",
    {
      "url": "http://localhost:3000/settings",
      "actions": ["wait for element #settings-form to be visible"]
    }
  ]
}

# CLI audit
npx lighthouse https://example.com \
  --only-categories=accessibility \
  --chrome-flags="--headless --no-sandbox" \
  --output=html --output-path=./a11y-report.html

// lighthouserc.json
{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000/", "http://localhost:3000/login"],
      "startServerCommand": "npm run start",
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", { "minScore": 0.9 }]
      }
    }
  }
}

test('enhanced contrast AAA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).withTags(['wcag2aaa']).analyze();
  if (results.violations.length > 0) {
    console.warn('AAA violations:', results.violations.map((v) => v.id));
  }
});

// Perceivable: images have alt text
test('images have alt text', async ({ page }) => {
  await page.goto('/');
  const images = await page.locator('img').all();
  for (const img of images) {
    const alt = await img.getAttribute('alt');
    const role = await img.getAttribute('role');
    expect(alt !== null || role === 'presentation').toBeTruthy();
  }
});

// Understandable: page language defined
test('page language defined', async ({ page }) => {
  await page.goto('/');
  const lang = await page.locator('html').getAttribute('lang');
  expect(lang).toBeTruthy();
  expect(lang!.length).toBeGreaterThanOrEqual(2);
});

// Robust: no duplicate IDs
test('no duplicate element IDs', async ({ page }) => {
  await page.goto('/');
  const duplicates = await page.evaluate(() => {
    const ids = Array.from(document.querySelectorAll('[id]')).map((el) => el.id);
    return ids.filter((id, i) => ids.indexOf(id) !== i);
  });
  expect(duplicates).toEqual([]);
});

test('status updates announced via live region', async ({ page }) => {
  await page.goto('/form');
  const liveRegion = page.locator('[aria-live="polite"], [role="status"]');
  await expect(liveRegion).toBeAttached();

  await page.getByRole('button', { name: 'Save' }).click();
  await expect(liveRegion).toHaveText(/saved successfully/i);
});

test('error alerts use assertive live region', async ({ page }) => {
  await page.goto('/form');
  const alertRegion = page.locator('[aria-live="assertive"], [role="alert"]');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(alertRegion).toContainText(/required/i);
});

test('interactive elements have accessible names', async ({ page }) => {
  await page.goto('/');

  for (const role of ['button', 'link'] as const) {
    const elements = await page.getByRole(role).all();
    for (const el of elements) {
      const name = await el.evaluate((e) =>
        e.getAttribute('aria-label') || e.getAttribute('aria-labelledby') || e.textContent?.trim()
      );
      expect(name).toBeTruthy();
    }
  }
});

test('no common ARIA mistakes', async ({ page }) => {
  await page.goto('/');

  // Clickable divs without proper roles
  const clickableDivs = await page.evaluate(() =>
    Array.from(document.querySelectorAll('div[onclick], span[onclick]'))
      .filter((el) => !el.getAttribute('role') && !el.getAttribute('tabindex'))
      .map((el) => el.outerHTML.substring(0, 100))
  );
  expect(clickableDivs).toEqual([]);

  // aria-hidden on focusable elements
  const hiddenFocusable = await page.evaluate(() =>
    Array.from(document.querySelectorAll('[aria-hidden="true"] a, [aria-hidden="true"] button, [aria-hidden="true"] input'))
      .filter((el) => el.getAttribute('tabindex') !== '-1')
      .map((el) => el.outerHTML.substring(0, 100))
  );
  expect(hiddenFocusable).toEqual([]);
});

test('tab order follows logical reading order', async ({ page }) => {
  await page.goto('/');

  const expectedOrder = ['Skip to main content', 'Home', 'Products', 'About', 'Contact', 'Search'];

  for (const expectedLabel of expectedOrder) {
    await page.keyboard.press('Tab');
    const focused = await page.evaluate(() => {
      const el = document.activeElement;
      return el?.getAttribute('aria-label') || el?.textContent?.trim() || '';
    });
    expect(focused).toContain(expectedLabel);
  }
});

test('shift+tab navigates backwards', async ({ page }) => {
  await page.goto('/');
  for (let i = 0; i < 5; i++) await page.keyboard.press('Tab');
  const fifth = await page.evaluate(() => document.activeElement?.textContent?.trim());
  await page.keyboard.press('Shift+Tab');
  const fourth = await page.evaluate(() => document.activeElement?.textContent?.trim());
  expect(fourth).not.toBe(fifth);
});

test('modal traps focus within dialog', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Open modal' }).click();
  await page.waitForSelector('[role="dialog"]');

  const dialog = page.locator('[role="dialog"]');
  const focusableInModal = await dialog.locator(
    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
  ).all();

  expect(focusableInModal.length).toBeGreaterThan(0);

  // Tab through and verify focus stays in modal
  for (let i = 0; i < focusableInModal.length + 2; i++) {
    await page.keyboard.press('Tab');
    const inside = await page.evaluate(() => {
      const dialog = document.querySelector('[role="dialog"]');
      return dialog?.contains(document.activeElement) ?? false;
    });
    expect(inside).toBe(true);
  }

  // Escape closes modal, focus returns to trigger
  await page.keyboard.press('Escape');
  await expect(dialog).not.toBeVisible();
  const triggerFocused = await page.getByRole('button', { name: 'Open modal' }).evaluate(
    (el) => el === document.activeElement
  );
  expect(triggerFocused).toBe(true);
});

test('skip navigation link works', async ({ page }) => {
  await page.goto('/');
  await page.keyboard.press('Tab');

  const skipLink = page.locator('a[href="#main-content"], a[href="#main"]');
  await expect(skipLink).toBeFocused();
  await expect(skipLink).toBeVisible();

  await page.keyboard.press('Enter');
  const mainFocused = await page.evaluate(() => {
    const active = document.activeElement;
    return active?.id === 'main-content' || active?.id === 'main' || active?.closest('main') !== null;
  });
  expect(mainFocused).toBe(true);
});

test('dropdown menu supports keyboard navigation', async ({ page }) => {
  await page.goto('/');
  const menuButton = page.getByRole('button', { name: 'Menu' });
  await menuButton.focus();

  await page.keyboard.press('Enter');
  const menu = page.getByRole('menu');
  await expect(menu).toBeVisible();

  await page.keyboard.press('ArrowDown');
  await expect(page.getByRole('menuitem').first()).toBeFocused();

  await page.keyboard.press('ArrowDown');
  await expect(page.getByRole('menuitem').nth(1)).toBeFocused();

  await page.keyboard.press('Escape');
  await expect(menu).not.toBeVisible();
  await expect(menuButton).toBeFocused();
});

test('tabs support arrow key navigation', async ({ page }) => {
  await page.goto('/tabs-page');
  const tabs = page.getByRole('tablist').getByRole('tab');

  await tabs.first().focus();
  await expect(tabs.first()).toHaveAttribute('aria-selected', 'true');

  await page.keyboard.press('ArrowRight');
  await expect(tabs.nth(1)).toBeFocused();
  await expect(tabs.nth(1)).toHaveAttribute('aria-selected', 'true');
  await expect(page.getByRole('tabpanel')).toBeVisible();
});

test('color contrast meets WCAG AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).withRules(['color-contrast']).analyze();
  expect(results.violations).toEqual([]);
});

test('animations respect prefers-reduced-motion', async ({ page }) => {
  await page.emulateMedia({ reducedMotion: 'reduce' });
  await page.goto('/');

  const hasAnimations = await page.evaluate(() => {
    for (const el of document.querySelectorAll('*')) {
      const styles = window.getComputedStyle(el);
      if (parseFloat(styles.animationDuration) > 0 || parseFloat(styles.transitionDuration) > 0) {
        if (!el.hasAttribute('data-essential-animation')) return true;
      }
    }
    return false;
  });
  expect(hasAnimations).toBe(false);
});

test.describe('Dark mode accessibility', () => {
  test('dark mode maintains contrast ratios', async ({ page }) => {
    await page.emulateMedia({ colorScheme: 'dark' });
    await page.goto('/');
    const results = await new AxeBuilder({ page }).withRules(['color-contrast']).analyze();
    expect(results.violations).toEqual([]);
  });

  test('light mode maintains contrast ratios', async ({ page }) => {
    await page.emulateMedia({ colorScheme: 'light' });
    await page.goto('/');
    const results = await new AxeBuilder({ page }).withRules(['color-contrast']).analyze();
    expect(results.violations).toEqual([]);
  });
});

test('touch targets meet minimum size', async ({ page }) => {
  await page.goto('/');

  const smallTargets = await page.evaluate(() => {
    const elements = document.querySelectorAll('a, button, input, select, textarea, [role="button"], [tabindex]');
    const violations: Array<{ html: string; width: number; height: number }> = [];

    elements.forEach((el) => {
      const rect = el.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      if (el.tagName === 'A' && el.closest('p')) return; // Skip inline text links

      if (rect.width < 44 || rect.height < 44) {
        violations.push({
          html: (el as HTMLElement).outerHTML.substring(0, 120),
          width: Math.round(rect.width),
          height: Math.round(rect.height),
        });
      }
    });
    return violations;
  });

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

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

  const unlabeledInputs = await page.evaluate(() => {
    const inputs = document.querySelectorAll(
      'input:not([type="hidden"]):not([type="submit"]):not([type="button"]), select, textarea'
    );
    const violations: string[] = [];

    inputs.forEach((input) => {
      const id = input.getAttribute('id');
      const hasExplicitLabel = id ? document.querySelector(`label[for="${id}"]`) !== null : false;
      const hasImplicitLabel = input.closest('label') !== null;
      const hasAria = input.getAttribute('aria-label') || input.getAttribute('aria-labelledby') || input.getAttribute('title');

      if (!hasExplicitLabel && !hasImplicitLabel && !hasAria) {
        violations.push((input as HTMLElement).outerHTML.substring(0, 100));
      }
    });
    return violations;
  });

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

test('form errors are announced to screen readers', async ({ page }) => {
  await page.goto('/form');
  await page.getByRole('button', { name: 'Submit' }).click();

  // Error messages should be in alert or live region
  const errorAnnouncement = await page.evaluate(() => {
    const errors = document.querySelectorAll('[role="alert"], [aria-live="assertive"], [aria-live="polite"]');
    return Array.from(errors).map((el) => el.textContent?.trim()).filter(Boolean);
  });
  expect(errorAnnouncement.length).toBeGreaterThan(0);

  // Each invalid field should have aria-describedby pointing to error
  const invalidFields = await page.locator('[aria-invalid="true"]').all();
  expect(invalidFields.length).toBeGreaterThan(0);

  for (const field of invalidFields) {
    const describedBy = await field.getAttribute('aria-describedby');
    expect(describedBy).toBeTruthy();
    const errorEl = page.locator(`#${describedBy}`);
    await expect(errorEl).toBeAttached();
    expect((await errorEl.textContent())?.trim().length).toBeGreaterThan(0);
  }
});

test('required fields are properly indicated', async ({ page }) => {
  await page.goto('/form');

  const requiredFields = await page.locator('[required], [aria-required="true"]').all();
  expect(requiredFields.length).toBeGreaterThan(0);

  for (const field of requiredFields) {
    const id = await field.getAttribute('id');
    const label = id ? page.locator(`label[for="${id}"]`) : page.locator('label').filter({ has: field });

    if (await label.count() > 0) {
      const labelText = await label.first().textContent();
      const hasIndicator = labelText?.includes('*') || labelText?.toLowerCase().includes('required');
      const hasAriaRequired = await field.getAttribute('aria-required') === 'true';
      const hasRequired = await field.getAttribute('required') !== null;
      expect(hasIndicator || hasAriaRequired || hasRequired).toBe(true);
    }
  }
});

test('inline validation messages are accessible', async ({ page }) => {
  await page.goto('/form');

  const emailField = page.getByLabel('Email');
  await emailField.fill('invalid-email');
  await emailField.blur();
  await page.waitForSelector('[role="alert"], .error-message');

  await expect(emailField).toHaveAttribute('aria-invalid', 'true');
  const describedBy = await emailField.getAttribute('aria-describedby');
  expect(describedBy).toBeTruthy();

  // Fix value and verify error clears
  await emailField.fill('[email protected]');
  await emailField.blur();
  const invalidAttr = await emailField.getAttribute('aria-invalid');
  expect(invalidAttr === null || invalidAttr === 'false').toBe(true);
});

<form novalidate aria-labelledby="form-title">
  <h2 id="form-title">Contact Us</h2>
  <p>Fields marked with * are required.</p>

  <div class="field">
    <label for="name">Full Name *</label>
    <input id="name" type="text" required aria-required="true"
      aria-describedby="name-hint name-error" autocomplete="name" />
    <span id="name-hint" class="hint">Enter your first and last name</span>
    <span id="name-error" class="error" role="alert" aria-live="assertive"></span>
  </div>

  <div class="field">
    <label for="email">Email Address *</label>
    <input id="email" type="email" required aria-required="true"
      aria-describedby="email-error" autocomplete="email" />
    <span id="email-error" class="error" role="alert" aria-live="assertive"></span>
  </div>

  <fieldset>
    <legend>Preferred Contact Method</legend>
    <div>
      <input type="radio" id="contact-email" name="contact" value="email" />
      <label for="contact-email">Email</label>
    </div>
    <div>
      <input type="radio" id="contact-phone" name="contact" value="phone" />
      <label for="contact-phone">Phone</label>
    </div>
  </fieldset>

  <button type="submit">Send Message</button>
</form>

# .github/workflows/accessibility.yml
name: Accessibility Tests

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run build
      - name: Start app
        run: npm run start &
        env:
          PORT: 3000
      - run: npx wait-on http://localhost:3000 --timeout 30000
      - name: axe-core tests
        run: npx playwright test --project=accessibility
      - name: pa11y-ci
        run: npx pa11y-ci --config .pa11yci.json
      - name: Lighthouse
        uses: treosh/lighthouse-ci-action@v12
        with:
          configPath: ./lighthouserc.json
          uploadArtifacts: true
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: accessibility-report
          path: playwright-report/
          retention-days: 14

// tests/accessibility/a11y-gate.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

const pages = ['/', '/login', '/dashboard', '/settings', '/form'];

for (const pagePath of pages) {
  test(`${pagePath} has no critical/serious a11y violations`, async ({ page }) => {
    await page.goto(pagePath);

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

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

    if (critical.length > 0) {
      console.error(`Violations on ${pagePath}:`, JSON.stringify(
        critical.map((v) => ({ rule: v.id, impact: v.impact, count: v.nodes.length })), null, 2
      ));
    }

    // Block on critical/serious; warn on moderate/minor
    expect(critical).toEqual([]);

    const moderate = results.violations.filter((v) => v.impact === 'moderate');
    if (moderate.length > 0) {
      console.warn(`Moderate on ${pagePath}:`, moderate.map((v) => v.id));
    }
  });
}

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'accessibility',
      testDir: './tests/accessibility',
      use: { browserName: 'chromium', baseURL: 'http://localhost:3000' },
    },
  ],
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    ['json', { outputFile: 'a11y-report.json' }],
  ],
});

// fixtures/a11y.fixture.ts
import { test as base, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

export const test = base.extend<{
  a11y: {
    assertNoViolations: (opts?: { tags?: string[]; exclude?: string[] }) => Promise<void>;
    assertNoCritical: () => Promise<void>;
    checkContrast: () => Promise<void>;
    checkForms: () => Promise<void>;
  };
}>({
  a11y: async ({ page }, use) => {
    await use({
      assertNoViolations: async (opts) => {
        let b = new AxeBuilder({ page }).withTags(opts?.tags ?? ['wcag2a', 'wcag2aa']);
        for (const s of opts?.exclude ?? []) b = b.exclude(s);
        expect((await b.analyze()).violations).toEqual([]);
      },
      assertNoCritical: async () => {
        const r = await new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']).analyze();
        expect(r.violations.filter((v) => v.impact === 'critical' || v.impact === 'serious')).toEqual([]);
      },
      checkContrast: async () => {
        expect((await new AxeBuilder({ page }).withRules(['color-contrast']).analyze()).violations).toEqual([]);
      },
      checkForms: async () => {
        expect((await new AxeBuilder({ page }).withRules(['label', 'select-name', 'autocomplete-valid']).analyze()).violations).toEqual([]);
      },
    });
  },
});

export { expect } from '@playwright/test';

import { test } from '../fixtures/a11y.fixture';

test('homepage is accessible', async ({ page, a11y }) => {
  await page.goto('/');
  await a11y.assertNoViolations();
});

test('form inputs are labeled', async ({ page, a11y }) => {
  await page.goto('/form');
  await a11y.checkForms();
});