test

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

将测试视为设计输入，而不是发布后的安全网。目标不是追求最高覆盖率，而是在避免团队陷入维护负担的同时，捕获最重要的缺陷。

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

必须完成的准备工作

用户通过 /test 启动此工作流。此技能启用后，加载 $frontend-design — 其中包含设计原则、反模式和上下文收集协议。继续之前，请遵循该协议 — 如果尚无设计上下文，必须先加载 $setup。此外，还需了解：目前最常逃逸到生产环境的 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 + Testing Library、Jest + 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 分钟）
• 测试失败会提供可操作的错误消息，而非晦涩难懂的堆栈跟踪
• 跨浏览器覆盖范围符合实际用户的浏览器分布
• 团队成员无需复杂设置即可在本地运行测试
• 测试数据具有确定性，测试执行期间不依赖外部服务