Automated Accessibility Testing with axe-core and jest-axe

1npm install --save-dev jest-axe @types/jest-axe

1// apps/web/src/components/auth/LoginForm.test.tsx
2import { render } from '@testing-library/react';
3import { axe, toHaveNoViolations } from 'jest-axe';
4import { LoginForm } from './LoginForm';
5
6expect.extend(toHaveNoViolations);
7
8describe('LoginForm accessibility', () => {
9  it('has no axe violations', async () => {
10    const { container } = render(<LoginForm onSubmit={jest.fn()} />);
11    const results = await axe(container);
12    expect(results).toHaveNoViolations();
13  });
14
15  it('has no violations with error state', async () => {
16    const { container } = render(
17      <LoginForm onSubmit={jest.fn()} error="Invalid credentials" />
18    );
19    const results = await axe(container);
20    expect(results).toHaveNoViolations();
21  });
22
23  it('has no violations while loading', async () => {
24    const { container } = render(<LoginForm onSubmit={jest.fn()} isLoading />);
25    const results = await axe(container);
26    expect(results).toHaveNoViolations();
27  });
28});

1import { axe } from 'jest-axe';
2
3// Run only specific WCAG rule sets
4const results = await axe(container, {
5  runOnly: {
6    type: 'tag',
7    values: ['wcag2a', 'wcag2aa', 'wcag21aa'],
8  },
9});
10
11// Disable a specific rule with documentation
12const results = await axe(container, {
13  rules: {
14    // Disable color-contrast check in unit tests
15    // (computed styles not available in jsdom)
16    'color-contrast': { enabled: false },
17  },
18});
19
20// Interpret violation output:
21// results.violations is an array of:
22// {
23//   id: 'button-name',
24//   impact: 'critical', // critical | serious | moderate | minor
25//   description: 'Ensures buttons have discernible text',
26//   nodes: [{ html: '<button>...</button>', target: ['button'] }]
27// }
28
29// Custom assertion with helpful error message:
30if (results.violations.length > 0) {
31  const report = results.violations.map(v =>
32    `[${v.impact}] ${v.id}: ${v.description}\n` +
33    v.nodes.map(n => '  HTML: ' + n.html.substring(0, 100)).join('\n')
34  ).join('\n\n');
35  throw new Error('Accessibility violations found:\n' + report);
36}

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

1import { test, expect } from '@playwright/test';
2import AxeBuilder from '@axe-core/playwright';
3
4test.describe('Page-level accessibility', () => {
5  test('courses page has no critical violations', async ({ page }) => {
6    await page.goto('/courses');
7    await page.waitForLoadState('networkidle');
8
9    const results = await new AxeBuilder({ page })
10      .withTags(['wcag2a', 'wcag2aa'])
11      .exclude('#cookie-banner')  // exclude third-party widget
12      .analyze();
13
14    // Filter to critical/serious only for CI gate
15    const blocking = results.violations.filter(v =>
16      ['critical', 'serious'].includes(v.impact || '')
17    );
18
19    expect(blocking).toHaveLength(0);
20  });
21
22  test('checks all states of interactive components', async ({ page }) => {
23    await page.goto('/courses');
24
25    // Check default state
26    let results = await new AxeBuilder({ page }).analyze();
27    expect(results.violations.filter(v => v.impact === 'critical')).toHaveLength(0);
28
29    // Open a modal and re-check
30    await page.click('[data-testid="filter-modal-trigger"]');
31    await page.waitForSelector('[role="dialog"]');
32    results = await new AxeBuilder({ page })
33      .include('[role="dialog"]')  // check only the modal
34      .analyze();
35    expect(results.violations.filter(v => v.impact === 'critical')).toHaveLength(0);
36  });
37});

1npm install --save-dev pa11y-ci

1// .pa11yci.json
2{
3  "defaults": {
4    "standard": "WCAG2AA",
5    "runners": ["axe", "htmlcs"],
6    "timeout": 10000,
7    "viewport": { "width": 1280, "height": 800 },
8    "ignore": ["color-contrast"]
9  },
10  "urls": [
11    "http://localhost:3000/",
12    "http://localhost:3000/courses",
13    "http://localhost:3000/login",
14    "http://localhost:3000/register"
15  ]
16}

1# .github/workflows/a11y.yml
2- name: Run pa11y-ci
3  run: |
4    npm start &
5    npx wait-on http://localhost:3000
6    npx pa11y-ci --reporter json > a11y-results.json 2>&1 || true
7    node -e "
8    const r = require('./a11y-results.json');
9    const total = Object.values(r.results).reduce((a, c) => a + c.issues?.length || 0, 0);
10    if (total > 0) { console.error(total + ' a11y issues found'); process.exit(1); }
11    console.log('PASS: No a11y issues');
12    "

1import { render, screen } from '@testing-library/react';
2import userEvent from '@testing-library/user-event';
3
4describe('Form accessibility with RTL', () => {
5  it('error message is associated with input via aria-describedby', async () => {
6    render(<EmailInput error="Invalid email format" />);
7
8    const input = screen.getByRole('textbox', { name: /email/i });
9    const errorId = input.getAttribute('aria-describedby');
10    expect(errorId).toBeTruthy();
11
12    const errorMsg = document.getElementById(errorId!);
13    expect(errorMsg).toHaveTextContent('Invalid email format');
14  });
15
16  it('loading state is communicated to screen readers', async () => {
17    render(<SubmitButton isLoading />);
18    // aria-busy or aria-label change communicates loading state
19    const button = screen.getByRole('button');
20    const isBusy = button.getAttribute('aria-busy') === 'true' ||
21                   button.textContent?.includes('Loading') ||
22                   button.getAttribute('aria-label')?.includes('loading');
23    expect(isBusy).toBe(true);
24    expect(button).toBeDisabled();
25  });
26
27  it('toast notification uses role=status for announcements', async () => {
28    render(<Toast message="Course enrolled successfully!" type="success" />);
29    // role=status or aria-live=polite for non-critical announcements
30    const toast = screen.getByRole('status');
31    expect(toast).toHaveTextContent('Course enrolled successfully!');
32  });
33});