a11y-testing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAccessibility Testing
无障碍测试
Automated accessibility testing with axe-core for WCAG 2.2 compliance. Catches 30-50% of issues automatically.
使用axe-core进行自动化无障碍测试，符合WCAG 2.2标准，可自动检测出30-50%的问题。
Overview
概述
- Implementing CI/CD accessibility gates
- Running pre-release compliance audits
- Testing component accessibility in unit tests
- Validating page-level accessibility with E2E tests
- Ensuring keyboard navigation works correctly
- 实现CI/CD无障碍门禁
- 运行发布前合规性审计
- 在单元测试中测试组件无障碍性
- 通过E2E测试验证页面级无障碍性
- 确保键盘导航正常工作
Quick Reference
快速参考
jest-axe Unit Testing
jest-axe 单元测试
typescript
// 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();
});typescript
// 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
Playwright + axe-core 端到端测试
typescript
// 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([]);
});typescript
// 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 Integration
CI/CD 集成
yaml
undefinedyaml
undefined.github/workflows/accessibility.yml
.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
undefinedname: 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
undefinedKey Decisions
关键决策
| Decision | Choice | Rationale |
|---|---|---|
| Test runner | jest-axe + Playwright | Unit + E2E coverage |
| WCAG level | AA (wcag2aa) | Industry standard, legal compliance |
| CI gate | Block on violations | Prevent regression |
| Browser matrix | Chromium + Firefox | Cross-browser coverage |
| Exclusions | Third-party widgets only | Minimize blind spots |
| Tags | wcag2a, wcag2aa, wcag22aa | Full WCAG 2.2 AA |
| State testing | Test all interactive states | Modal, error, loading |
| 决策项 | 选择方案 | 理由说明 |
|---|---|---|
| 测试运行器 | jest-axe + Playwright | 单元测试+E2E测试全覆盖 |
| WCAG 级别 | AA (wcag2aa) | 行业标准，符合合规要求 |
| CI 门禁 | 发现问题则阻止合并 | 防止无障碍性退化 |
| 浏览器矩阵 | Chromium + Firefox | 跨浏览器覆盖 |
| 排除范围 | 仅第三方组件 | 减少检测盲区 |
| 标签 | wcag2a, wcag2aa, wcag22aa | 完整覆盖WCAG 2.2 AA级别 |
| 状态测试 | 测试所有交互状态 | 弹窗、错误、加载状态等 |
Anti-Patterns (FORBIDDEN)
反模式（禁止使用）
typescript
// 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 latetypescript
// 错误示例：全局禁用规则
const results = await axe(container, {
rules: { 'color-contrast': { enabled: false } } // 绝对不要禁用规则
});
// 错误示例：排除范围过大
new AxeBuilder({ page })
.exclude('body') // 失去无障碍测试的意义
.analyze();
// 错误示例：仅测试正常流程
it('form is accessible', async () => {
const { container } = render(<Form />);
expect(await axe(container)).toHaveNoViolations();
// 缺失：错误状态、加载状态、禁用状态的测试
});
// 错误示例：无CI强制执行
// 存在无障碍测试但不阻止PR合并
// 错误示例：仅依赖手动测试
// 完全依赖人工审核——发现问题太晚Related Skills
相关技能
- - Playwright E2E testing patterns
e2e-testing - - Jest unit testing fundamentals
unit-testing - - Accessible component foundations
design-system-starter
- - Playwright E2E测试模式
e2e-testing - - Jest单元测试基础
unit-testing - - 无障碍组件基础
design-system-starter
Capability Details
能力详情
jest-axe-testing
jest-axe-testing
Keywords: jest, axe, unit test, component test, react-testing-library
Solves:
- Component-level accessibility validation
- Fast feedback in development
- CI/CD unit test gates
- Testing all component states (disabled, error, loading)
关键词: jest, axe, 单元测试, 组件测试, react-testing-library
解决的问题:
- 组件级无障碍性验证
- 开发阶段快速反馈
- CI/CD单元测试门禁
- 测试组件所有状态（禁用、错误、加载）
playwright-axe-testing
playwright-axe-testing
Keywords: playwright, e2e, axe-core, page scan, wcag, integration
Solves:
- Full page accessibility audits
- Testing interactive states (modals, menus, forms)
- Multi-browser accessibility verification
- WCAG compliance validation at page level
关键词: playwright, e2e, axe-core, 页面扫描, wcag, 集成
解决的问题:
- 整页无障碍性审计
- 测试交互状态（弹窗、菜单、表单）
- 多浏览器无障碍性验证
- 页面级WCAG合规性验证
ci-a11y-gates
ci-a11y-gates
Keywords: ci, cd, github actions, accessibility gate, automation
Solves:
- Blocking PRs with accessibility violations
- Automated regression prevention
- Compliance reporting and artifacts
- Integration with deployment pipelines
关键词: ci, cd, github actions, 无障碍门禁, 自动化
解决的问题:
- 阻止存在无障碍问题的PR合并
- 自动防止无障碍性退化
- 合规性报告与工件生成
- 与部署流水线集成