manual-testing

手动无障碍测试技能

规范来源：mgifford/ACCESSIBILITY.md 中的 examples/MANUAL_ACCESSIBILITY_TESTING_GUIDE.md 此技能源自该文件。如有疑问，以示例为准。

规划或审查手动无障碍测试时，请遵循以下规则。

---

严重程度等级（此技能）

等级	含义
Critical（严重）	问题完全阻碍一个或多个残障群体完成核心任务
Serious（较严重）	显著妨碍访问；不应要求用户采用不合理的变通方法
Moderate（中等）	造成使用障碍；存在负担不大的变通方法
Minor（轻微）	未达到最佳实践；对访问的影响较小

---

核心原则

手动测试能发现自动化工具无法检测的问题，包括：

• 屏幕阅读器播报质量和用户体验
• 键盘导航流程和逻辑顺序
• 动态界面中的焦点管理
• 为辅助技术用户提供的上下文和方向信息
• 强制颜色模式（Windows 高对比度）——自动化工具无法模拟操作系统级别的颜色覆盖
• 真实世界中的可用性障碍

---

Critical：何时必须进行手动测试

请在以下情况下进行手动测试：

• 每次发布前——端到端测试关键用户流程
• UI 变更后——测试所有受影响的组件
• 新增功能时——测试完整的用户工作流
• 自动化测试通过时——验证实际用户体验
• 报告无障碍 Bug 时——复现问题并验证修复

**入门指南：**先测试仅使用键盘的情况（最容易入门），然后学习适用于你所用平台的基本屏幕阅读器命令。先在熟悉的网站上练习，再测试自己的产品。每次专注于一个组件或流程。

---

Critical：仅使用键盘进行测试

每个交互元素都必须能够仅通过键盘访问和操作。

步骤：

1. 点击浏览器地址栏，然后按 Tab，从页面顶部开始
2. 按 Tab 遍历整个页面；检查每个可聚焦元素：
   • 焦点是否可见（清晰的轮廓或高亮）？
   • 焦点顺序是否合理（符合视觉顺序或阅读顺序）？
   • 能否激活该元素？（链接和按钮使用 Enter；按钮和复选框使用 Space）
3. 按 Shift+Tab 反向遍历元素
4. 确认没有键盘陷阱（能否按 Tab 离开每个元素？）

需要验证的快捷键：

按键	预期行为
Tab	向前移动焦点
Shift+Tab	向后移动焦点
Enter	激活链接和按钮；提交表单
Space	激活按钮；切换复选框
方向键	在组件内导航（菜单、选项卡、单选按钮组）
Escape	关闭对话框；取消操作
Home / End	跳转到组件的开头或结尾

针对组件的检查：

• **表单：**所有字段均可访问；标签和必填状态会被播报；错误会显示并被播报；Enter 可提交；适用时可以取消或重置
• **按钮：**Enter 和 Space 都能激活；激活时有视觉反馈；激活后焦点会移至恰当位置
• **链接：**Enter 可激活；链接文本能清楚说明目标；跳转链接可正常使用
• **下拉菜单/选择菜单：**方向键可浏览选项；Escape 可关闭；选中值会被播报
• **模态对话框：**打开时焦点移入；焦点被限制在对话框内；按 Escape 可关闭（关键对话框除外）；关闭后焦点返回触发按钮
• **自定义组件（选项卡、折叠面板、轮播）：**遵循 WAI-ARIA 键盘操作模式；方向键和 Home/End 按照文档正常工作；状态变化清晰可辨

---

重要：屏幕阅读器测试

推荐的平台组合：

• NVDA + Firefox 或 Chrome（Windows）
• JAWS + Chrome 或 Firefox（Windows）
• VoiceOver + Safari（macOS / iOS）
• TalkBack + Chrome（Android）

基本测试步骤：

1. 启动屏幕阅读器（NVDA：Ctrl+Alt+N；VoiceOver macOS：Cmd+F5）
2. 按标题导航（NVDA/JAWS：H / Shift+H）——标题是否构成清晰的逻辑大纲？
3. 按地标导航（NVDA/JAWS：D / Shift+D）——是否能识别 <nav>、<main>、<header>？
4. 按表单控件导航（NVDA/JAWS：F / Shift+F）——是否会读出标签？
5. 阅读所有内容——顺序是否合理？是否有遗漏或令人困惑的播报？

针对特定组件的屏幕阅读器检查：

• **图像：**忽略装饰性图像（alt 为空或使用 aria-hidden）；信息性图像具有描述性替代文本；复杂图像具有更长的描述
• **链接：**仅凭播报内容即可明确链接用途；文本有意义（不是“点击这里”）；会指出外部链接或新窗口
• **按钮：**标签描述其操作；会播报按下/切换状态；会播报禁用状态
• **表单字段：**先播报标签，再播报字段类型；会播报必填状态、说明/提示、错误消息和成功消息
• **动态内容：**通过实时区域播报新增/删除的内容；传达加载状态和进度
• **表格：**按行/单元格导航（NVDA/JAWS 中使用 Ctrl+Alt+Arrow）；每个单元格都会播报列标题和行标题；表格用途明确（通过标题或 aria-label）
• **自定义小组件：**会播报角色（例如，“选项卡”“菜单”“对话框”）；会播报状态（例如，“已选中”“已展开”）；为复杂小组件提供操作说明

请对每个交互元素进行以下验证：

• 会播报元素类型（按钮、链接、标题……）
• 标签/名称清晰且具有描述性
• 会播报当前值（表单字段）
• 会播报状态（已选中、已选择、已展开……）
• 会播报更改（动态更新、实时区域）

严重：强制颜色模式测试

**自动化工具为何会漏掉这一点：**强制颜色由操作系统级设置触发，该设置会用受限的系统调色板替换所有作者定义的颜色。自动化工具无法模拟操作系统级覆盖，无法检测自定义颜色被移除后哪些元素会变得不可见，也无法评估焦点指示器、图标和自定义控件能否经受替换。

启用方法：

• **Windows 11：**设置 → 辅助功能 → 对比度主题 → 选择主题 → 应用
• **Windows 10：**设置 → 轻松使用 → 高对比度 → 开启（或按 Alt+Left Shift+Print Screen）
• **Chrome/Edge DevTools：**F12 → 更多工具 → 渲染 → “模拟 CSS 媒体功能 forced-colors” → active
• Firefox：about:config → ui.forcedColors → 设置为 1（设为 -1 可重置）
• Polypane 内置强制颜色模拟面板

发布前务必使用实际操作系统设置进行验证 — DevTools 模拟很方便，但并不完全等效。

检查要点：

• 所有文本在其背景上都清晰可读（Canvas 上的 CanvasText）
• 按钮边界清晰可见；链接与正文文本可区分；表单字段有可见边框
• 键盘焦点轮廓清晰可见（outline 会保留；box-shadow 可能不会）
• SVG 图标清晰可见（fill/stroke 使用 currentColor）
• 自定义复选框 / 单选按钮仍然清晰可见且易于区分；切换状态通过文本 / ARIA / 轮廓显示，而非仅依赖颜色
• 错误状态无需仅依赖颜色即可识别；必填字段通过文本或图标标记，而非仅通过颜色
• 传达含义的背景图像有文本 / ARIA 替代内容
• 图表 / 数据可视化提供图案 / 纹理 / 标签替代方案

常见修复方法：

问题	修复方法
box-shadow 焦点环消失	改用 outline
SVG 图标不可见	fill/stroke 使用 currentColor
自定义复选框不可见	添加可见边框；使用 forced-color-adjust 覆盖
仅通过颜色标记错误	添加图标、文本标签或 aria-invalid
输入框不可见（border: none）	在 @media (forced-colors: active) 中添加 border: 1px solid ButtonBorder
背景图像被移除	添加可见文本、说明文字或 aria-label

用于修补的 CSS 系统颜色关键字：

@media (forced-colors: active) {
  :focus-visible {
    outline: 3px solid Highlight;
    outline-offset: 2px;
  }
  .custom-checkbox::before {
    forced-color-adjust: none;
    border: 2px solid ButtonBorder;
    background-color: ButtonFace;
  }
  .custom-checkbox[aria-checked="true"]::before {
    background-color: Highlight;
  }
}

相关关键字：Canvas、CanvasText、ButtonFace、ButtonText、 ButtonBorder、Highlight、HighlightText、LinkText、VisitedText、GrayText。

仅在万不得已时才使用 forced-color-adjust: none — 它会使元素完全退出强制颜色模式，可能抵消用户的辅助功能设置。

---

中等：视觉辅助功能检查

颜色对比度

• 正文文本（< 18 pt 或 < 14 pt 粗体）：最低 4.5:1
• 大号文本（≥ 18 pt 或 ≥ 14 pt 粗体）：最低 3:1
• UI 组件和图形：最低 3:1
• 焦点指示器：与相邻颜色的对比度为 3:1

使用以下工具测试：WebAIM Contrast Checker、浏览器 DevTools。分别测试浅色和深色模式。

SC 1.4.4 调整文本大小与 SC 1.4.10 重排——不要混为一谈

这是两个不同的成功标准，测试方法也各不相同。页面可能通过其中一个，却未通过另一个；在 200% 缩放时出现水平滚动，也不一定意味着任一标准未通过。

**SC 1.4.4 调整文本大小（AA）：**内容必须能够放大至 200%，且不丢失内容或功能。此标准专门检查文本放大，本身并不要求消除水平滚动。

1. 将浏览器缩放比例设为 200%（Ctrl/Cmd + +）
2. 确认所有内容清晰可读，且没有被截断或重叠
3. 确认功能（菜单、表单、控件）在 200% 缩放时仍可使用
4. 还要使用操作系统级屏幕放大功能进行测试（Windows 放大镜、macOS 缩放）

**SC 1.4.10 重排（AA）：**在等效于 320 CSS 像素的视口宽度下，内容必须能够呈现，且不丢失信息或功能，也不需要在两个维度上滚动（在桌面端进行此项测试的一种常见方法，是将 1280px 宽的视口缩放至 400%——两者等效）。

1. 将视口宽度设为 320 CSS 像素（或将 1280px 视口缩放至 400%）
2. 对于不属于例外范围的内容，确认阅读时不需要水平滚动——参见下文的例外情况
3. 确认没有内容被截断、重叠或隐藏
4. 确认交互元素仍可操作
5. 确认阅读顺序、关系和操作方式均得以保留，不依赖原有的视觉布局

例外情况，具体而言：SC 1.4.10 仅豁免使用或含义上需要二维布局的内容部分，而非整个页面。规范中的示例包括：数据表格、地图、图表、视频播放器、游戏、演示文稿，以及需要始终显示工具栏的界面。某个组件属于例外范围，并不意味着页面其余部分也豁免（数据表格上方的标题、筛选器、搜索和分页仍必须重排）。即使在属于例外范围的组件内，个别部分也可能仍需重排。“需要”是对含义的判断，而非对便利性的判断——如果某个组件只是采用宽幅固定布局时看起来更好，而重排后并不会丢失信息或功能，则不属于豁免范围。

如果页面在 400% 缩放时（或等效的 320px 视口下）触发水平滚动，这是一个很有价值的信号，表明可能尚未实现重排；但在判定失败之前，应先调查溢出的内容是否属于例外范围。请参阅 行为可访问性自动化 （skills/behavioral-a11y/SKILL.md），了解可复用且经过测试的 Playwright 重排风险指标及其记录在案的局限性——它只是一个指标，并非重排符合性检查；仍需人工判断以确认例外范围、核实内容未被截断，并在 400% 缩放下测试实际内容。

焦点指示器：三个不同的成功标准

SC 2.4.7 焦点可见（AA）： 每个可通过键盘聚焦的元素都必须有 可见的焦点指示器。这是一项二元检查——要么存在可见的指示器， 要么不存在。

• 每个可聚焦元素的焦点指示器都可见
• 除非有更好的替代方案，否则不得移除焦点指示器
• 焦点指示器不会被其他内容遮挡

SC 1.4.11 非文本对比度（AA）： UI 组件上的焦点指示器与相邻颜色之间的 对比度至少为 3:1。此要求适用于指示器本身，而非组件的正常状态。

• 焦点指示器与相邻颜色之间的对比度达到 3:1，测量时应比较 指示器颜色与相邻背景／组件颜色
• 自定义焦点样式满足对比度要求（不只是默认轮廓）

SC 2.4.13 焦点外观（AAA）： 要求比 SC 2.4.7 更严格——焦点指示器的 最小面积必须等于可聚焦元素周长 × 2 CSS 像素，聚焦与未聚焦状态之间的 对比度必须达到 3:1，且指示器不得被作者创建的内容完全遮挡。目标等级为 AA 的 项目无需满足此项，但满足此项能提供更强的 无障碍支持；请记录你的项目是否以此为目标。

行为截图差异测试： CWAC 项目的 FocusIndicatorAudit 会发送真实的 Tab 按键操作，并比较每次按键前后的整页截图；如果没有像素发生变化， 就会报告一条发现。它不会测量对比度（SC 1.4.11），无法证明检测到的变化位于 聚焦元素本身（其比较范围是整页），无法判断指示器是否足够明显，也无法区分指示器缺失与 指示器被其他内容遮挡。本仓库自己的可复用实现 （skills/behavioral-a11y/SKILL.md， focus-visible-risk.mjs） 是对所述方法的独立重新实现，不同之处在于，它会针对每个元素，截取其周围带有内边距区域的 全新未聚焦／聚焦截图对。这弥补了 CWAC 整页比较方法的部分局限， 同时也带来了自身已记录的权衡。任何一种实现，或任何单独使用的截图差异方法， 都无法验证 SC 1.4.11（对比度）或 SC 2.4.13（最小面积）。请将截图差异测试作为补充检查，与人工验证结合使用， 而不要将其作为唯一的焦点指示器测试。

---

按组件类型划分的测试工作流

表单： 仅使用键盘导航至表单 → 填写所有字段（检查 Tab 顺序）→ 触发验证错误 → 确认错误已显示并播报 → 修正后重新验证 → 使用 Enter／Space 提交 → 确认成功消息已播报。使用屏幕阅读器时， 还要确认字段标签／说明／类型都已播报，且错误的朗读顺序符合逻辑。

模态对话框： 激活触发器 → 确认焦点移入模态框 → 使用 Tab 遍历所有元素 → 确认 Tab 不会离开模态框（焦点陷阱）→ 按 Escape 或点击 关闭按钮关闭 → 确认焦点返回触发器。使用屏幕阅读器时，确认模态框已播报（role="dialog"、aria-labelledby）， 且内容的朗读顺序符合逻辑。

单页应用： 点击导航链接 → 确认内容发生变化 → 确认焦点移至主标题／内容 → 确认页面标题发生变化 → 确认路由变化已播报，或焦点能提供上下文。确认后退按钮正常工作，且新页面结构（地标、标题）清晰。

---

记录测试结果

对于发现的每个问题，请记录：测试的组件／页面（URL 或名称）、问题 描述、预期行为、带编号的复现步骤、辅助技术名称／版本、浏览器名称／版本、 操作系统名称／版本，以及严重程度。还可附上截图／录屏和违反的 WCAG 成功标准。

## Accessibility Issue: [Brief Description]

**Component:** [URL or component name]
**Issue:** [Description of what doesn't work]
**Expected:** [What should happen]
**Severity:** [Critical/High/Medium/Low]

**Steps to Reproduce:**
1. [Step 1]
2. [Step 2]

**Testing Environment:**
- **Screen Reader:** [Name and version]
- **Browser:** [Name and version]
- **OS:** [Operating system and version]

**WCAG Criterion:** [If applicable]
**Suggested Fix:** [If you have one]

（如需记录结构化发现，请使用 skills/bug-reporting/SKILL.md。）

---

鼓励残障人士参与

残障人士最擅长发现障碍并验证解决方案——他们的亲身经历能揭示自动化工具和非残障测试人员容易忽略的问题，还能验证修复是否真正有效。

• 消除参与障碍：提供清晰、没有行话的说明；安排灵活的时间；接受异步反馈；为测试时间提供报酬；提供无障碍的问题报告格式
• 邀请不同群体的测试人员：屏幕阅读器用户、仅使用键盘的用户、语音控制用户、认知障碍用户、多重残障用户
• 公平地致谢并酬谢测试人员；为他们持续参与创造机会

---

快速参考清单

30 分钟键盘测试： 从头到尾按 Tab 键；确认焦点始终可见；激活所有按钮（Enter/Space）和链接（Enter）；填写并提交表单；打开/关闭模态框；使用自定义控件；浏览菜单；检查是否存在键盘陷阱。

30 分钟屏幕阅读器测试： 按标题、地标和表单字段导航；朗读整页内容；激活按钮/链接；填写并提交表单；测试自定义控件；确认图片有替代文本；确认屏幕阅读器会播报动态内容更新。

视觉无障碍快速检查： 200% 缩放；焦点指示器是否可见；颜色对比度（文本和 UI 组件）；确认内容不依赖颜色也能阅读；浅色和深色模式；强制颜色模式。

---

完成标准清单

• 已完成键盘测试；所有交互均可通过键盘访问和操作
• 未发现键盘陷阱
• 焦点顺序符合逻辑
• 已至少使用一种平台组合完成屏幕阅读器测试
• 所有图片、图标和图表都有正确的文本替代
• 屏幕阅读器会播报动态内容变化
• 已验证文本和 UI 组件的颜色对比度
• 已测试所有自定义 UI 组件在强制颜色模式下的表现
• 已测试 200% 缩放；内容未被截断，也无需水平滚动
• 在适用情况下，已运行表单、模态框和 SPA 导航的组件工作流测试
• 已记录发现的问题，包含 URL、元素、WCAG 成功标准、严重程度和复现步骤

---

WCAG 关键标准

• 1.1.1 非文本内容（A）
• 1.3.1 信息和关系（A）
• 1.4.1 颜色的使用（A）
• 1.4.3 对比度（最低）（AA）
• 1.4.11 非文本对比度（AA）
• 2.1.1 键盘（A）
• 2.1.2 无键盘陷阱（A）
• 2.4.3 焦点顺序（A）
• 2.4.7 焦点可见（AA）
• 2.4.11 焦点外观（AA — WCAG 2.2）
• 4.1.2 名称、角色、值（A）
• 4.1.3 状态消息（AA）

---

参考资料

• 完整指南
• skills/behavioral-a11y/SKILL.md — 重排风险和焦点可见风险的自动化指标及其已记录的局限性
• WebAIM：使用 NVDA 进行测试
• WebAIM：使用 VoiceOver
• WebAIM：屏幕阅读器测试
• Deque：屏幕阅读器键盘快捷键
• WAI-ARIA 编写实践指南
• W3C：简易检查——初步审查
• MDN：forced-colors 媒体特性

标准展望： 这些规则以 WCAG 2.2 AA 为目标。 请关注：https://www.w3.org/TR/wcag-3.0/