accessibility-selenium-testing

使用 Selenium WebDriver 和 Axe Core 进行无障碍测试

此技能使用 axe-core 引擎，在 Selenium WebDriver 框架中执行自动化无障碍分析，直接在浏览器中检测 WCAG 违规问题和最佳实践问题。

激活条件： 当你需要验证 WCAG 合规性、扫描无障碍违规问题、测试键盘导航、审核 ARIA 语义或生成 a11y 报告时，此技能会触发。

首先要询问的问题

• 涉及哪些应用 URL 或用户流程？哪些内容明确不在范围内？
• 是否已有 Selenium 环境？CI 如何运行？
• 目标标准是什么（默认采用 WCAG 2.2 AA）？是否有组织特定的政策？
• 哪些页面或组件风险最高（身份验证、结账、表单、模态框、导航）？
• 是否存在需要例外处理的已知限制（遗留标记、第三方小组件）？

前提条件

组件	版本	用途
Java JDK	21+	提供现代功能的运行环境
Maven	3.9+	依赖管理
Selenium WebDriver	4.x	浏览器自动化
axe-core-selenium	4.10+	Deque axe-core 集成
JUnit 5	5.10+	测试框架
AssertJ	3.x	流式断言，让失败信息更易读
Allure	2.x	附带 a11y 违规信息的报告

注意： 使用 com.deque.html.axe-core:selenium Maven 依赖集成 axe。

---

目标： WCAG 2.2 AA（wcag2a、wcag2aa、wcag21a、wcag21aa、wcag22a、wcag22aa）。请参阅 WCAG 2.2 规范。

请勿用于

• Playwright/TypeScript 无障碍测试（请使用 a11y-playwright-testing）。
• 编写 Selenium 功能性 UI 测试（请使用 webapp-selenium-testing）。
• 完整的合规性签署——axe 自动扫描只能发现约 30-50% 的问题；仍需进行人工审核和辅助技术测试。

Axe-Core 工具参考

AxeBuilder 配置

方法	用途	示例
new AxeBuilder()	创建扫描器实例	入口点
.withTags(List<String>)	按 WCAG 标签筛选	wcag2aa、wcag21aa、wcag22aa
.include(String)	扫描指定选择器	#main-content
.exclude(String)	跳过指定选择器	.third-party-widget
.disableRules(List<String>)	禁用指定规则	color-contrast
.withRules(List<String>)	仅运行指定规则	label、button-name
.analyze(WebDriver)	执行扫描	返回 Results

Results 对象

方法	返回值	用途
getViolations()	List<Rule>	未通过的规则
getPasses()	List<Rule>	已通过的规则
getIncomplete()	List<Rule>	需要人工审核的规则
getInapplicable()	List<Rule>	不适用于页面的规则
violationFree()	boolean	无违规问题时返回 True

违规影响级别

影响	严重程度	CI 操作
严重	完全阻碍用户使用	始终使构建失败
高	造成重大障碍	始终使构建失败
中等	使用存在一定困难	发出警告或使构建失败
轻微	造成不便	记录以供审核

---

分步工作流

工作流 1：在现有测试中添加 A11y 扫描

1. 在 pom.xml 中添加依赖

   <dependency>
       <groupId>com.deque.html.axe-core</groupId>
       <artifactId>selenium</artifactId>
       <version>4.10.0</version>
   </dependency>
   

2. 创建 AccessibilityHelper 工具类

   • 请参阅 Axe 模式：辅助扫描

3. 在页面加载后添加扫描

   driver.get("https://example.com");
   waitForPageReady();
   AccessibilityHelper.verifyPageAccessibility(driver);
   

4. 运行并检查违规问题

   mvn test -Dtest=A11yTest
   

工作流 2：测试特定组件

1. 导航到组件可见的页面

2. 触发组件状态（打开模态框、显示下拉菜单）

3. 仅扫描该组件

   Results results = new AxeBuilder()
       .withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
       .include("#login-modal")
       .analyze(driver);
   

4. 断言并记录

工作流 3：键盘导航审计

1. 识别所有交互元素
2. 以编程方式通过 Tab 键遍历页面

   element.sendKeys(Keys.TAB);
   WebElement focused = driver.switchTo().activeElement();
   

3. 验证焦点顺序是否合乎逻辑
4. 测试 Escape 键能否关闭模态框
5. 验证不存在键盘陷阱

工作流 4：集成 CI

1. 配置无头浏览器

   mvn test -Dheadless=true -Dgroups=a11y
   

2. 将严重/重大问题的容忍度设为零

   long criticalCount = violations.stream()
       .filter(v -> List.of("critical", "serious").contains(v.getImpact()))
       .count();
   assertThat(criticalCount).isZero();
   

3. 生成 JSON 报告以便跟踪

---

代码模式

完整的 AxeBuilder 扫描模式、违规记录、JUnit 5 集成和 CI/CD YAML，请参阅 references/code-patterns.md。

关键代码片段：

Results results = new AxeBuilder()
    .withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"))
    .analyze(driver);
assertThat(results.violationFree()).as("A11y violations").isTrue();

故障排除

问题	原因	解决方案
Axe 返回空结果	页面尚未完全加载	添加明确的等待，直到页面就绪状态
对比度误报	动态主题	测试浅色和深色模式
第三方小组件存在违规	无法修改供应商代码	使用 .exclude() 并记录对应工单
规则不完整	需要手动审核	记录以便手动审计，不要自动判定失败
不同运行的结果不同	异步内容加载	确保扫描前页面状态确定
CI 失败但本地通过	视口/浏览器不同	使用与 CI 相同的无头配置

---

按 POUR 原则分类

原则	重点领域	常见违规
可感知性	文本替代内容、字幕、对比度、结构	缺少 alt 文本、对比度低、缺少标签
可操作性	键盘访问、焦点顺序、跳过区块	键盘陷阱、没有跳过链接、焦点不可见
可理解性	标签、可预测行为、错误处理	指示不清、意外更改
稳健性	有效 HTML、ARIA、名称/角色/值	无效 ARIA、重复 ID、缺少角色

---

运行测试

Maven 命令

命令	用途
mvn test -Dgroups=a11y	运行所有无障碍测试
mvn test -Dtest=A11yTest	运行指定测试类
mvn test -Dheadless=true	以无头模式运行（CI 模式）
mvn allure:serve	查看包含违规项的 Allure 报告

集成 CI/CD

- name: Run Accessibility Tests
  run: mvn test -Dgroups=a11y -Dheadless=true

- name: Upload A11y Report
  uses: actions/upload-artifact@v3
  with:
    name: a11y-report
    path: target/a11y-results/

---

危险信号

• 将 axe 扫描无违规视为完全符合 WCAG——自动化仅覆盖约 30-50% 的标准。
• 全局禁用规则，而不是使用限定范围的 .exclude() 并记录整改工单。
• 页面完全加载前就开始扫描——异步内容会导致虚假的“0 violations”。
• 因 incomplete 规则导致构建失败——这些规则需要手动审核，而非自动判定失败。

---

参考资料

• Axe 模式：辅助扫描 - Maven 配置和 AccessibilityHelper 扫描方法
• Axe 模式：辅助处理 - AccessibilityHelper 结果、筛选、记录和报告
• Axe 模式：标签与测试 - 常见 axe 标签参考和测试模式
• Axe 模式：键盘与 CI/CD - 键盘导航测试和 CI/CD 集成
• Axe-Core API 参考 - 完整的 AxeBuilder 配置、Results 对象和影响级别
• WCAG 2.2 AA 清单：可感知性与可操作性 - 手动审计清单、POUR 原则 1-2
• WCAG 2.2 AA 清单：可理解性与稳健性 - 手动审计清单、POUR 原则 3-4 和辅助技术
• WCAG 2.2 AA 清单：新增内容与例外情况 - WCAG 2.2 新增内容、例外情况模板、W3C 参考资料
• Deque Axe 规则 - 规则说明
• W3C WCAG 2.2 - 官方规范
• WAI-ARIA 实践 - 小组件模式

---

验证

• Axe WebDriver 审核通过 — AxeBuilder.analyze(driver) 返回的严重违规项为零
• 键盘无障碍性已验证 — 使用 Tab 键导航可到达所有交互元素
• 符合 WCAG 2.2 AA 标准 — 所有 AA 级规则均通过（包括 WCAG 2.2 新增要求：焦点不被遮挡、拖动操作、目标尺寸最小值）