test

通过合理组合视觉回归、交互测试和无障碍断言，系统地确保 UI 行为可靠。

将测试视为设计输入，而不是发布后的安全网。目标不是追求最高覆盖率，而是在不让团队陷入维护负担的前提下，捕获最重要的错误。

如果测试策略需要自动化 axe 检查、屏幕阅读器验证或键盘遍历测试，请参阅无障碍测试参考文档。 如果要测试自定义组件的焦点管理、ARIA 正确性和键盘行为，请参阅组件无障碍参考文档。 如果要验证工作流在压力、错误或边缘情况下的表现，请参阅交互设计参考文档。 如果要测试验证行为、可恢复的字段错误或放弃操作的路径，请参阅错误恢复参考文档。 如果要测试加载状态、骨架屏、过时数据提示或感知性能行为，请参阅加载反馈与感知性能参考文档。

必须完成的准备工作

阅读 frontend-design 并遵循其上下文收集流程。复用已有上下文，只针对影响重大的信息缺口提问。此外，还要了解：当前最常逃逸到生产环境的 UI 错误、团队对测试维护的容忍度，以及 UI 中哪些部分变化最频繁。

评估测试需求

找出哪些方面正在出问题，以及哪些问题应当被捕获：

1. 梳理错误逃逸路径：

   • 视觉回归（意外的布局偏移、间距错误、资源缺失）
   • 交互故障（按钮无响应、表单损坏、链接失效）
   • 状态错误（数据过时、竞态条件、加载状态不正确）
   • 无障碍缺陷（缺少标签、键盘陷阱、颜色对比度不达标）
   • 跨浏览器或跨设备的不一致

2. 评估当前覆盖情况：

   • 已经测试了什么？哪些测试虽然存在，却无法提供有效信号？
   • 哪些测试会随机失败并因此被忽略（不稳定的测试会损害信任）？
   • 测试套件需要运行多久？运行缓慢的套件容易被绕过。

3. 根据风险和变更频率确定优先级：

   • 高流量的用户路径（结账、注册、核心工作流）
   • 经常变化的 UI 界面（设计系统组件）
   • 历史上已知容易出错的区域
   • 无障碍至关重要的界面（表单、导航、模态框）

测试维度

视觉回归

在视觉变更发布前捕获非预期的变化。

捕获内容：

• 组件状态（默认、悬停、焦点、活动、禁用、加载、错误）
• 具有代表性断点的整页布局
• 跨浏览器渲染差异（焦点样式、表单控件、字体）

基线管理规范：

• 将基线视为团队资产，而非个人截图
• 在拉取请求中审核有意的变更，而不是等到合并后
• 在有意更新设计后立即重新建立基线，以免产生干扰

减少不稳定因素的做法：

• 截图前等待字体、图像和动画稳定下来
• 模拟或冻结动态内容（时间戳、随机数据、动画）
• 使用确定性的测试数据和固定的视口尺寸
• 隔离测试，避免网络波动；对 API 响应进行存根处理

范围边界：

• 全面测试设计系统组件
• 仅在少数关键断点测试页面布局，而不是测试每一种像素宽度
• 不要测试由你无法控制的第三方小组件（嵌入内容、广告）

交互测试

验证用户操作是否产生正确结果。

组件级交互：

• 表单提交、验证和错误恢复
• 模态框的打开/关闭、焦点陷阱和 Escape 键行为
• 下拉菜单、手风琴、标签页和折叠面板的状态转换
• 按钮操作及其副作用

用户流程验证：

• 多步骤工作流（结账、引导、向导流程）
• 导航和路由行为
• 浏览器前进/后退时的状态持久化
• 并发操作（快速点击、重复提交）

测试数据策略：

• 使用真实但确定的数据
• 覆盖边缘情况（空输入、最大长度、特殊字符）
• 包含错误状态响应，而不只是成功场景的存根

无障碍断言

将无障碍验证纳入测试流水线。

自动化检查（每次构建时运行）：

• 使用 axe-core 或同等工具检查违反 WCAG 规则的情况
• 颜色对比度最低要求（普通文本为 4.5:1，大号文本 / UI 组件为 3:1）
• 语义 HTML 验证（标题顺序、地标区域、标签关联）
• 焦点管理（可见的焦点指示器、合理的 Tab 键顺序）

键盘遍历测试：

• 无需鼠标即可使用 Tab 键完成整个流程
• 验证所有交互元素均可访问
• 确认模态框中的焦点陷阱和退出方式均有效
• 测试跳过链接和绕过区块是否正常工作

屏幕阅读器冒烟测试（针对关键路径）：

• 动态内容变化的播报（实时区域）
• 有意义的无障碍名称和描述
• 状态播报（展开/折叠、已选中、必填）
• 能够传达给辅助技术的错误消息

动态效果和动画：

• 验证是否遵循 prefers-reduced-motion
• 确认没有可能诱发癫痫的闪烁（每秒少于 3 次）

UI 测试金字塔

平衡速度、信心和维护成本：

层级	范围	速度	用途
单元（组件）	单个组件，依赖项已模拟	快（< 1s）	逻辑、渲染、属性处理
集成（组件 + 上下文）	使用真实提供程序、存根的组件	中（< 10s）	交互行为、状态转换
端到端（完整浏览器）	真实浏览器、真实网络或存根	慢（每项测试 < 30s）	关键用户流程、跨页面行为
视觉回归	截图对比	中（可并行）	非预期的视觉变化

指导原则：

• 尽可能将测试下沉到金字塔底层。对于按钮行为，组件测试比 E2E 测试更快、更精确。
• 将 E2E 留给跨多个页面或需要真实浏览器行为（路由、身份验证、支付）的用户旅程。
• 每次拉取请求时都在 CI 中运行视觉回归，而不只是发布前运行。

工具选择

根据团队的技术栈和测试层选择工具：

需求	优选方案	注意事项
组件单元测试/集成测试	Vitest + React Testing Library、Jest + React Testing Library	优先使用能反映用户行为的 Testing Library 查询
端到端关键流程	Playwright、Cypress	Playwright 速度快且支持跨浏览器并行测试；Cypress 设置更简单
视觉回归	Chromatic、Loki、Playwright screenshots、Percy	Chromatic 适合与 Storybook 集成；Playwright 适合自行管理基线
无障碍自动化	axe-core、@axe-core/react、Playwright + axe	集成到 CI；在基线达到要求之前，将检查结果视为警告而非阻断项
交互/用户流程	Playwright、Cypress、Storybook Test Runner	Storybook Test Runner 适用于隔离的组件交互；Playwright/Cypress 适用于完整流程

务实规则：

• 优先使用一种 E2E 工具和一种组件测试工具。工具过多会分散专业知识。
• 如果项目使用 Storybook，应先在那里添加交互测试，再引入单独的组件测试套件。
• 将无障碍检查集成到现有测试运行器中，而不是另设一套工具链。

反模式

• 测试实现细节：断言用户能看到和执行的内容，而不是内部状态或 CSS 类名。
• 忽视不稳定的测试：不稳定的测试比没有测试更糟。应立即修复或删除。
• 所有测试都通过 E2E 完成：运行缓慢的测试套件会让人不愿执行测试。应将逻辑下沉到组件测试中。
• 对所有内容都做快照测试：快照测试能捕获变化，却无法说明意图。应谨慎使用，仅用于确保标记稳定，而非测试行为。
• 将无障碍测试与主流程分开：每个迭代周期仅手动运行一次的无障碍检查，无法持续发现问题。
• 模拟浏览器环境：E2E 和视觉回归应使用真实浏览器。jsdom 和 happy-dom 适用于组件逻辑测试，不适用于布局或交互保真度测试。
• 测试第三方小组件：不要为你无法控制的嵌入内容、地图、广告或聊天小组件建立基线或进行断言。
• 跳过跨浏览器测试：至少要在用户实际使用的浏览器中验证焦点样式、表单控件和布局。
• 让基线过时：过时的基线会掩盖回归问题。发生预期内的视觉变化后，应更新基线。

验证测试的可信度

发布测试策略前：

• 已对风险最高的用户流程进行自动化测试
• 已在拉取请求中审查视觉基线
• 无障碍检查在 CI 中运行，且基线干净或已记录例外情况
• 已识别不稳定的测试，并已修复或移除
• 完整测试套件的运行时间不超过团队的耐心阈值（目标：CI 反馈时间 < 5 分钟）
• 测试失败会产生可采取行动的错误消息，而不是含糊不清的堆栈跟踪
• 跨浏览器覆盖范围符合实际用户的浏览器分布
• 团队成员无需复杂设置即可在本地运行测试
• 测试数据具有确定性，测试执行期间不依赖外部服务