Back to Details

accessibility-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

可访问性测试（中文版）

Accessibility Testing (Chinese Version)

英文版： 见技能 
accessibility-testing-en
。
提示词见本目录 
prompts/accessibility-testing.md
。
English Version: See the skill 
accessibility-testing-en
.
Prompt templates can be found in 
prompts/accessibility-testing.md
in this directory.

何时使用

When to Use

  • 用户提到「可访问性测试」「accessibility testing」「a11y」「WCAG」
  • 需要根据 WCAG 标准设计可访问性测试策略、测试用例、测试方案
  • 触发示例：「根据以下需求设计可访问性测试用例」「做一份 WCAG 2.1 合规性测试方案」
  • When users mention "accessibility testing", "a11y", or "WCAG"
  • When you need to design accessibility testing strategies, test cases, and plans based on WCAG standards
  • Trigger Examples: "Design accessibility test cases based on the following requirements" "Create a WCAG 2.1 compliance testing plan"

输出格式选项

Output Format Options

本技能默认输出为 Markdown（与 Standard-version 模板一致）。若需其他格式，请在需求末尾明确说明：
格式说明如何请求（示例）
Markdown默认，便于阅读与版本管理无需额外说明
Excel制表符分隔，可粘贴到 Excel「请以 Excel 可粘贴的制表符分隔表格输出」
CSV逗号分隔，首行为表头「请以 CSV 格式输出」
JSON便于程序解析「请以 JSON 形式输出」
详细说明与示例见本目录 output-formats.md。
This skill outputs Markdown by default (consistent with the Standard-version template). To request other formats, clearly specify at the end of your requirements:
FormatDescriptionHow to Request (Example)
MarkdownDefault, easy to read and version controlNo additional instructions needed
ExcelTab-separated, can be pasted into Excel"Please output as a tab-separated table compatible with Excel"
CSVComma-separated, first row as header"Please output in CSV format"
JSONEasy for program parsing"Please output in JSON format"
Detailed explanations and examples can be found in output-formats.md in this directory.

如何使用本技能中的提示词

How to Use the Prompts in This Skill

  1. 打开本目录 
    prompts/accessibility-testing.md
    ，将虚线以下内容复制到 AI 对话。
  2. 附加你的功能需求或系统规格。
  3. 若需 Excel/CSV/JSON，在末尾加上 output-formats.md 中的请求句。
  1. Open 
    prompts/accessibility-testing.md
    in this directory, copy the content below the dashed line into your AI conversation.
  2. Attach your functional requirements or system specifications.
  3. If you need Excel/CSV/JSON, add the request phrase from output-formats.md at the end.

参考文件

Reference Files

  • prompts/accessibility-testing.md — 可访问性测试 Standard-version 提示词
  • output-formats.md — Markdown / Excel / CSV / JSON 请求说明
  • prompts/accessibility-testing.md — Standard-version prompts for accessibility testing
  • output-formats.md — Instructions for requesting Markdown / Excel / CSV / JSON formats

代码示例 | Code Examples

Code Examples | Code Examples

本技能提供以下真实代码示例：
  1. axe-core + Playwright 自动化测试 - 完整的可访问性自动化测试套件
    • 12个测试用例
    • 覆盖 WCAG 2.1 Level A/AA
    • 包含自动化和手工测试指南
    • 详细的违规报告
  2. WCAG 2.1 手工测试清单（即将推出）
  3. 屏幕阅读器测试指南（即将推出）
查看 examples/ 目录获取更多示例。
This skill provides the following real code examples:
  1. axe-core + Playwright Automation Testing - Complete accessibility automation testing suite
    • 12 test cases
    • Covers WCAG 2.1 Level A/AA
    • Includes automation and manual testing guidelines
    • Detailed violation reports
  2. WCAG 2.1 Manual Testing Checklist (Coming soon)
  3. Screen Reader Testing Guidelines (Coming soon)
Check the examples/ directory for more examples.

常见误区 | Common Pitfalls

Common Pitfalls | Common Pitfalls

  • ❌ 只依赖自动化工具 → ✅ 结合自动化工具（30%覆盖）和手工测试（70%覆盖）
  • ❌ 忽略键盘导航 → ✅ 确保所有功能可通过键盘访问
  • ❌ 颜色对比度不足 → ✅ 使用工具检查对比度，确保至少 4.5:1（正常文本）
  • ❌ 缺少替代文本 → ✅ 为所有图片、图标提供有意义的 alt 文本
  • ❌ 表单标签缺失 → ✅ 确保所有表单控件有关联的 label
  • ❌ 只在开发完成后测试 → ✅ 在设计和开发阶段就考虑可访问性
  • ❌ Relying solely on automation tools → ✅ Combine automation tools (30% coverage) with manual testing (70% coverage)
  • ❌ Ignoring keyboard navigation → ✅ Ensure all functions are accessible via keyboard
  • ❌ Insufficient color contrast → ✅ Use tools to check contrast, ensure at least 4.5:1 (normal text)
  • ❌ Missing alternative text → ✅ Provide meaningful alt text for all images and icons
  • ❌ Missing form labels → ✅ Ensure all form controls have associated labels
  • ❌ Testing only after development is complete → ✅ Consider accessibility during design and development phases

最佳实践 | Best Practices

Best Practices | Best Practices

  1. WCAG 合规性
    • 遵循 WCAG 2.1 Level AA 标准（最低要求）
    • 使用自动化工具检测常见问题
    • 进行手工测试验证复杂交互
    • 使用真实的辅助技术测试
  2. 测试策略
    • 在 CI/CD 中集成自动化可访问性测试
    • 定期进行手工测试和用户测试
    • 使用多种工具交叉验证
    • 记录和追踪可访问性问题
  3. 关键测试点
    • 键盘导航（Tab、Enter、Esc、方向键）
    • 屏幕阅读器兼容性（NVDA、JAWS、VoiceOver）
    • 颜色对比度和视觉设计
    • 表单可访问性
    • 语义化 HTML
    • ARIA 属性正确使用
  4. 工具选择
    • axe-core：自动化测试（最全面）
    • Lighthouse：快速审计
    • WAVE：可视化问题
    • 屏幕阅读器：真实用户体验
  5. 文档和报告
    • 清晰记录违规项和严重程度
    • 提供修复建议和代码示例
    • 追踪修复进度
    • 定期生成合规性报告
  1. WCAG Compliance
    • Follow WCAG 2.1 Level AA standards (minimum requirement)
    • Use automation tools to detect common issues
    • Conduct manual testing to verify complex interactions
    • Test with real assistive technologies
  2. Testing Strategy
    • Integrate automated accessibility testing into CI/CD
    • Conduct regular manual testing and user testing
    • Cross-verify with multiple tools
    • Document and track accessibility issues
  3. Key Testing Points
    • Keyboard navigation (Tab, Enter, Esc, arrow keys)
    • Screen reader compatibility (NVDA, JAWS, VoiceOver)
    • Color contrast and visual design
    • Form accessibility
    • Semantic HTML
    • Correct use of ARIA attributes
  4. Tool Selection
    • axe-core: Automation testing (most comprehensive)
    • Lighthouse: Quick audits
    • WAVE: Visual issue detection
    • Screen readers: Real user experience testing
  5. Documentation and Reporting
    • Clearly document violations and their severity
    • Provide repair suggestions and code examples
    • Track repair progress
    • Generate regular compliance reports

故障排除 | Troubleshooting

Troubleshooting | Troubleshooting

问题1：axe-core 报告过多误报

Issue 1: axe-core reports too many false positives

症状：自动化测试报告大量问题，但实际上是误报
解决方案：
  1. 配置规则排除已知误报：
    typescript
    await new AxeBuilder({ page })
  .disableRules(['color-contrast']) // 排除特定规则
  .analyze();
  2. 使用标签过滤：
    typescript
    await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa']) // 只检查 WCAG 2.1 A/AA
  .analyze();
  3. 手工验证可疑问题
  4. 更新到最新版本的 axe-core
Symptoms: Automation testing reports numerous issues that are actually false positives
Solutions:
  1. Configure rules to exclude known false positives:
    typescript
    await new AxeBuilder({ page })
  .disableRules(['color-contrast']) // Exclude specific rules
  .analyze();
  2. Filter using tags:
    typescript
    await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa']) // Only check WCAG 2.1 A/AA
  .analyze();
  3. Manually verify suspicious issues
  4. Update to the latest version of axe-core

问题2：无法检测动态内容的可访问性问题

Issue 2: Unable to detect accessibility issues in dynamic content

症状：模态框、下拉菜单等动态内容的问题未被检测
解决方案：
  1. 在触发动态内容后再运行测试：
    typescript
    await page.click('[data-testid="open-modal"]');
await page.waitForSelector('[role="dialog"]');
const results = await new AxeBuilder({ page }).analyze();
  2. 针对特定区域测试：
    typescript
    await new AxeBuilder({ page })
  .include('[role="dialog"]')
  .analyze();
  3. 测试不同状态下的可访问性
Symptoms: Issues with dynamic content like modals, dropdown menus are not detected
Solutions:
  1. Run tests after triggering dynamic content:
    typescript
    await page.click('[data-testid="open-modal"]');
await page.waitForSelector('[role="dialog"]');
const results = await new AxeBuilder({ page }).analyze();
  2. Test specific regions:
    typescript
    await new AxeBuilder({ page })
  .include('[role="dialog"]')
  .analyze();
  3. Test accessibility in different states

问题3：键盘导航测试不通过

Issue 3: Keyboard navigation tests fail

症状：某些元素无法通过键盘访问
解决方案：
  1. 检查 tabindex 属性：
    html
    <!-- ✅ 推荐：使用 tabindex="0" 使元素可聚焦 -->
<div role="button" tabindex="0">Click me</div>

<!-- ❌ 避免：tabindex > 0 会破坏自然的 Tab 顺序 -->
<div tabindex="5">Bad practice</div>
  2. 使用语义化 HTML：
    html
    <!-- ✅ 推荐：原生按钮自动可聚焦 -->
<button>Click me</button>

<!-- ❌ 不推荐：需要额外的可访问性属性 -->
<div onclick="...">Click me</div>
  3. 添加键盘事件处理：
    typescript
    element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    // 处理激活
  }
});
Symptoms: Some elements cannot be accessed via keyboard
Solutions:
  1. Check tabindex attributes:
    html
    <!-- ✅ Recommended: Use tabindex="0" to make elements focusable -->
<div role="button" tabindex="0">Click me</div>

<!-- ❌ Avoid: tabindex > 0 breaks natural Tab order -->
<div tabindex="5">Bad practice</div>
  2. Use semantic HTML:
    html
    <!-- ✅ Recommended: Native buttons are automatically focusable -->
<button>Click me</button>

<!-- ❌ Not recommended: Requires additional accessibility attributes -->
<div onclick="...">Click me</div>
  3. Add keyboard event handlers:
    typescript
    element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    // Handle activation
  }
});

问题4：颜色对比度不足

Issue 4: Insufficient color contrast

症状：axe-core 报告颜色对比度问题
解决方案：
  1. 使用对比度检查工具：
    • Chrome DevTools Lighthouse
    • WebAIM Contrast Checker
    • Colour Contrast Analyser
  2. 确保对比度至少：
    • 正常文本：4.5:1
    • 大文本（18pt+）：3:1
    • UI 组件：3:1
  3. 调整颜色方案：
    css
    /* ❌ 对比度不足 */
color: #999; /* 灰色文本 */
background: #fff; /* 白色背景 */

/* ✅ 对比度充足 */
color: #595959; /* 深灰色文本 */
background: #fff; /* 白色背景 */
Symptoms: axe-core reports color contrast issues
Solutions:
  1. Use contrast checking tools:
    • Chrome DevTools Lighthouse
    • WebAIM Contrast Checker
    • Colour Contrast Analyser
  2. Ensure contrast ratios of at least:
    • Normal text: 4.5:1
    • Large text (18pt+): 3:1
    • UI components: 3:1
  3. Adjust color schemes:
    css
    /* ❌ Insufficient contrast */
color: #999; /* Gray text */
background: #fff; /* White background */

/* ✅ Sufficient contrast */
color: #595959; /* Dark gray text */
background: #fff; /* White background */

问题5：屏幕阅读器无法正确读取内容

Issue 5: Screen readers cannot read content correctly

症状：使用屏幕阅读器时内容混乱或缺失
解决方案：
  1. 使用语义化 HTML：
    html
    <!-- ✅ 推荐 -->
<nav>
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>

<!-- ❌ 不推荐 -->
<div class="nav">
  <div class="item">Home</div>
</div>
  2. 正确使用 ARIA 属性：
    html
    <!-- ✅ 推荐：提供有意义的标签 -->
<button aria-label="关闭对话框">×</button>

<!-- ❌ 不推荐：屏幕阅读器只会读"乘号" -->
<button>×</button>
  3. 使用 aria-live 通知动态变化：
    html
    <div aria-live="polite" aria-atomic="true">
  <!-- 动态内容 -->
</div>
Symptoms: Content is messy or missing when using screen readers
Solutions:
  1. Use semantic HTML:
    html
    <!-- ✅ Recommended -->
<nav>
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>

<!-- ❌ Not recommended -->
<div class="nav">
  <div class="item">Home</div>
</div>
  2. Use ARIA attributes correctly:
    html
    <!-- ✅ Recommended: Provide meaningful labels -->
<button aria-label="Close dialog">×</button>

<!-- ❌ Not recommended: Screen readers will only read "multiplication sign" -->
<button>×</button>
  3. Use aria-live to notify dynamic changes:
    html
    <div aria-live="polite" aria-atomic="true">
  <!-- Dynamic content -->
</div>

问题6：表单可访问性问题

Issue 6: Form accessibility issues

症状：表单控件缺少标签或错误提示不清晰
解决方案：
  1. 关联 label 和 input：
    html
    <!-- ✅ 推荐：显式关联 -->
<label for="email">邮箱</label>
<input id="email" type="email" />

<!-- ✅ 推荐：隐式关联 -->
<label>
  邮箱
  <input type="email" />
</label>
  2. 提供清晰的错误提示：
    html
    <input
  id="email"
  type="email"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">
  请输入有效的邮箱地址
</span>
  3. 使用 fieldset 和 legend 分组：
    html
    <fieldset>
  <legend>联系方式</legend>
  <!-- 表单控件 -->
</fieldset>
Symptoms: Form controls lack labels or error messages are unclear
Solutions:
  1. Associate labels with inputs:
    html
    <!-- ✅ Recommended: Explicit association -->
<label for="email">Email</label>
<input id="email" type="email" />

<!-- ✅ Recommended: Implicit association -->
<label>
  Email
  <input type="email" />
</label>
  2. Provide clear error messages:
    html
    <input
  id="email"
  type="email"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">
  Please enter a valid email address
</span>
  3. Use fieldset and legend for grouping:
    html
    <fieldset>
  <legend>Contact Information</legend>
  <!-- Form controls -->
</fieldset>

问题7：CI 环境中测试失败

Issue 7: Tests fail in CI environment

症状：本地通过但 CI 环境中可访问性测试失败
解决方案：
  1. 确保 CI 环境安装了浏览器：
    yaml
    - name: Install Playwright
  run: npx playwright install --with-deps
  2. 检查环境差异（字体、渲染）
  3. 保存失败时的截图和报告：
    typescript
    if (violations.length > 0) {
  await page.screenshot({ path: 'a11y-violations.png' });
  fs.writeFileSync('a11y-report.json', JSON.stringify(violations));
}
  4. 使用 Docker 容器保证环境一致性
Symptoms: Passes locally but accessibility tests fail in CI environment
Solutions:
  1. Ensure browsers are installed in CI environment:
    yaml
    - name: Install Playwright
  run: npx playwright install --with-deps
  2. Check environment differences (fonts, rendering)
  3. Save screenshots and reports when tests fail:
    typescript
    if (violations.length > 0) {
  await page.screenshot({ path: 'a11y-violations.png' });
  fs.writeFileSync('a11y-report.json', JSON.stringify(violations));
}
  4. Use Docker containers to ensure environment consistency

获取更多帮助

Get More Help

如果问题仍未解决：
  1. 查看 FAQ.md
  2. 查看示例的 README.md 文件
  3. 参考 WCAG 2.1 官方文档
  4. 使用 WebAIM 资源
  5. 提交新的 Issue 并附上详细信息
相关技能： functional-testing、manual-testing、automation-testing、test-case-writing。
If the issue is still not resolved:
  1. Check FAQ.md
  2. Check the README.md files in the examples
  3. Refer to the official WCAG 2.1 documentation
  4. Use WebAIM resources
  5. Submit a new Issue with detailed information
Related Skills: functional-testing, manual-testing, automation-testing, test-case-writing.