a11y-testing

无障碍测试

使用 axe-core 自动进行无障碍测试，确保符合 WCAG 2.2 标准。可自动发现 30-50% 的问题。

概述

• 实施 CI/CD 无障碍门禁
• 执行发布前合规审计
• 在单元测试中测试组件的无障碍性
• 通过 E2E 测试验证页面级无障碍性
• 确保键盘导航正常运行

快速参考

jest-axe 单元测试

// jest.setup.ts
import { toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

// Button.test.tsx
import { render } from '@testing-library/react';
import { axe } from 'jest-axe';

it('has no a11y violations', async () => {
  const { container } = render(<Button>Click me</Button>);
  expect(await axe(container)).toHaveNoViolations();
});

Playwright + axe-core E2E

// e2e/accessibility.spec.ts
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("page has no a11y violations", async ({ page }) => {
  await page.goto("/");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag22aa"])
    .analyze();
  expect(results.violations).toEqual([]);
});

test("modal state has no violations", async ({ page }) => {
  await page.goto("/");
  await page.click('[data-testid="open-modal"]');
  await page.waitForSelector('[role="dialog"]');

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

CI/CD 集成

# .github/workflows/accessibility.yml
name: Accessibility
on: [pull_request]

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: npm run test:a11y
      - run: npm run build
      - run: npx playwright install --with-deps chromium
      - run: npm start & npx wait-on http://localhost:3000
      - run: npx playwright test e2e/accessibility

关键决策

决策	选择	理由
测试运行器	jest-axe + Playwright	覆盖单元测试 + E2E
WCAG 级别	AA（wcag2aa）	行业标准，满足法律合规要求
CI 门禁	违规时阻止	防止回归
浏览器矩阵	Chromium + Firefox	覆盖多个浏览器
排除项	仅第三方小组件	将盲点降至最低
标签	wcag2a, wcag2aa, wcag22aa	完整覆盖 WCAG 2.2 AA
状态测试	测试所有交互状态	模态框、错误、加载

反模式（禁止）

// BAD: Disabling rules globally
const results = await axe(container, {
  rules: { 'color-contrast': { enabled: false } }  // NEVER disable rules
});

// BAD: Excluding too much
new AxeBuilder({ page })
  .exclude('body')  // Defeats the purpose
  .analyze();

// BAD: Only testing happy path
it('form is accessible', async () => {
  const { container } = render(<Form />);
  expect(await axe(container)).toHaveNoViolations();
  // Missing: error state, loading state, disabled state
});

// BAD: No CI enforcement
// Accessibility tests exist but don't block PRs

// BAD: Manual-only testing
// Relying solely on human review - catches issues too late

相关技能

• e2e-testing - Playwright E2E 测试模式
• unit-testing - Jest 单元测试基础
• design-system-starter - 无障碍组件基础

能力详情

jest-axe-testing

关键词： jest、axe、单元测试、组件测试、react-testing-library 解决的问题：

• 组件级无障碍验证
• 在开发过程中快速获得反馈
• CI/CD 单元测试门禁
• 测试组件的所有状态（禁用、错误、加载）

playwright-axe-testing

关键词： playwright、e2e、axe-core、页面扫描、wcag、集成 解决的问题：

• 全页面无障碍审计
• 测试交互状态（模态框、菜单、表单）
• 验证多浏览器无障碍性
• 在页面级别验证 WCAG 合规性

ci-a11y-gates

关键词： ci、cd、github actions、无障碍门禁、自动化 解决的问题：

• 阻止存在无障碍违规的 PR
• 自动防止回归
• 合规报告和构建产物
• 与部署流水线集成