accessibility-testing

无障碍测试

整合版：如需通过多种工具（axe-core + pa11y + Lighthouse）进行全面的 WCAG 审核、视频无障碍检查和问题修复，建议使用 /a11y-ally。本技能提供基本无障碍测试模式的快速参考卡。

浏览器引擎

浏览器驱动的无障碍检查应通过 qe-browser 车队技能执行。vibium a11y-tree --json 会返回完整的无障碍树，且不会进行视觉渲染——将其传入 axe-core，通过 vibium eval --stdin 执行规则集检查。参见 .claude/skills/qe-browser/SKILL.md。

<default_to_action> 测试无障碍性或确保合规时：

1. 应用 POUR 原则：可感知、可操作、可理解、健壮
2. 通过仅使用键盘的方式进行测试（Tab、Enter、Escape）
3. 使用屏幕阅读器验证（VoiceOver、NVDA、JAWS）
4. 检查颜色对比度（文本为 4.5:1，大号文本为 3:1）
5. 使用 axe-core 自动化测试，并集成到 CI/CD 流水线中

无障碍快速检查清单：

• 所有图片都有替代文本（装饰性图片使用 alt=""）
• 所有表单字段都有标签
• 颜色绝不是唯一的指示方式
• 所有交互元素都能显示焦点
• 键盘导航在整个界面中均可使用

关键成功因素：

• 自动化测试可发现 30-50% 的问题
• 必须使用真实辅助技术进行手动测试
• 测试中应纳入残障用户 </default_to_action>

快速参考卡

适用场景

• 法律合规（ADA、Section 508、EU Directive）
• 新功能开发
• 发布前验证
• 无障碍审计

WCAG 2.2 级别

级别	要求	目标
A	基本无障碍	法律最低要求
AA	标准（大多数组织）	行业标准
AAA	增强	专业网站

POUR 原则

原则	含义	关键测试
可感知	能够感知内容	替代文本、对比度、字幕
可操作	能够操作 UI	键盘、避免诱发癫痫、导航
可理解	能够理解	标签清晰、行为可预测、错误提示
健壮	兼容辅助技术	有效 HTML、ARIA

颜色对比度要求

内容	AA 比率	AAA 比率
普通文本	4.5:1	7:1
大号文本（18pt+）	3:1	4.5:1
UI 组件	3:1	-

---

键盘导航测试

// Test all interactive elements reachable via keyboard
test('all interactive elements keyboard accessible', async ({ page }) => {
  await page.goto('/');

  const focusableElements = await page.$$('button, a, input, select, textarea, [tabindex]');

  for (const element of focusableElements) {
    await element.focus();
    const isFocused = await element.evaluate(el => document.activeElement === el);
    expect(isFocused).toBe(true);
  }
});

// Verify visible focus indicator
test('focus indicator visible', async ({ page }) => {
  await page.goto('/');
  await page.keyboard.press('Tab');

  const focusedElement = await page.locator(':focus');
  const outline = await focusedElement.evaluate(el =>
    getComputedStyle(el).outline
  );

  expect(outline).not.toBe('none');
});

---

使用 axe-core 进行自动化测试

首选：通过 a11y-ally AQE 技能（qe-browser + Vibium）

新项目应使用 a11y-ally 技能——它将 qe-browser（Vibium WebDriver BiDi）与 axe-core、pa11y 和 Lighthouse 组合使用，并生成带有 WCAG 标记和问题修复指导的 JSON 报告。它无需安装 300MB 的 Playwright，且已接入 AQE 车队。

# Runs axe-core + pa11y + Lighthouse via qe-browser (Vibium) engine
aqe skill run a11y-ally -- --url https://example.com --wcag AA

备用方案：Playwright + @axe-core/playwright

如果你已有 Playwright 测试套件且不想引入第二个浏览器运行器，或者需要 Vibium 目前仅支持 Chrome 的 BiDi 后端尚不支持的 Firefox/Safari 覆盖范围，请保留此方案。

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

test('page has no accessibility violations', async ({ page }) => {
  await page.goto('/');

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

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

// CI/CD integration
test('checkout flow accessible', async ({ page }) => {
  await page.goto('/checkout');

  const results = await new AxeBuilder({ page })
    .include('#checkout-form')
    .disableRules(['color-contrast']) // Fix in next sprint
    .analyze();

  expect(results.violations.filter(v =>
    v.impact === 'critical' || v.impact === 'serious'
  )).toHaveLength(0);
});

---

屏幕阅读器测试清单

## VoiceOver (macOS) Testing
- [ ] Page title announced on load
- [ ] Headings hierarchy correct (h1 → h2 → h3)
- [ ] Landmarks present (nav, main, footer)
- [ ] Images have descriptive alt text
- [ ] Form labels read correctly
- [ ] Error messages announced
- [ ] Dynamic content updates announced (aria-live)

---

Agent 驱动的无障碍测试

// Comprehensive a11y validation
await Task("Accessibility Validation", {
  url: 'https://example.com/checkout',
  standard: 'WCAG2.2',
  level: 'AA',
  checks: ['keyboard', 'screen-reader', 'color-contrast'],
  includeScreenReaderSimulation: true
}, "qe-visual-tester");

// Fleet coordination for comprehensive testing
const a11yFleet = await FleetManager.coordinate({
  strategy: 'comprehensive-accessibility',
  agents: [
    'qe-visual-tester',     // Visual & keyboard checks
    'qe-test-generator',    // Generate a11y tests
    'qe-quality-gate'       // Enforce compliance
  ],
  topology: 'parallel'
});

---

Agent 协作提示

记忆命名空间

aqe/accessibility/
├── wcag-results/*       - WCAG audit results
├── screen-reader/*      - Screen reader test logs
├── remediation/*        - Fix recommendations
└── compliance/*         - Compliance reports

车队协作

const a11yFleet = await FleetManager.coordinate({
  strategy: 'accessibility-testing',
  agents: [
    'qe-visual-tester',   // axe-core, keyboard, focus
    'qe-test-generator',  // Generate a11y test cases
    'qe-quality-gate'     // Block non-compliant builds
  ],
  topology: 'parallel'
});

---

相关技能

• visual-testing-advanced - 视觉无障碍检查
• mobile-testing - 移动端无障碍（VoiceOver、TalkBack）
• compliance-testing - 法律合规

---

请记住

全球有 10 亿人有残障。无法访问的软件将全球 15% 的人口排除在外。法律要求：ADA、Section 508、EU Directive 2016/2102。购买力达 13 万亿美元。诉讼数量增加 250% 以上。

自动化测试只能发现 30%–50% 的问题。 应结合手动键盘测试、屏幕阅读器测试，以及与残障人士进行真实用户测试。

借助 Agent： Agent 可自动执行 WCAG 2.2 合规性检查、屏幕阅读器模拟和焦点管理验证。利用 Agent 在 CI/CD 中强制执行无障碍标准，并在上线前发现违规问题。