testing-frontend-code

name	testing-frontend-code
description	用可测试性约束来设计、实现、重构或评审前端业务代码。当需要选择单元测试、集成测试或 E2E，修复前端缺陷并补回归测试，测试异步队列、上传、审批、竞态或重试，分离业务决策与 UI、网络、路由、状态管理、存储等副作用，或治理缓慢脆弱的前端 E2E 测试时使用。不用于修复测试运行器配置、测试第三方库、纯视觉回归或纯后端测试。

前端代码可测试性

可观测标记与交付要求

• 加载本 Skill 后，第一条用户可见回复必须以 🧪 开头，让用户能够确认 Skill 已生效。该要求只适用于启用后的第一条回复。
• 完成需求实现与测试后，必须在最终回复中直接向开发者提交一份相关的实施报告，不创建或修改报告文件。报告结构不限，但应如实说明完成内容、测试结果，以及未完成或未验证事项；不得把测试失败或未执行写成已通过。

用验证成本指导代码结构：业务决策应当便宜地验证，副作用应当留在系统边界。

工作流

1. 读取仓库指引、相关源码、调用链、现有测试和验证命令。不要只根据需求描述设计方案。
2. 列出本次改动涉及的业务决策，明确输入、可观察输出、副作用、异步状态，以及时间、随机数、ID、网络、存储、进程通信等会改变结果的外部可变条件。确认这些条件集中在测试可控制或替换的边界，而不是散落在业务判断中。
3. 修复缺陷或改变既有契约时，先添加能复现问题的最小失败测试，再修改实现。
4. 只调整本次任务触及的代码：
   • 若业务分支与副作用混在一起，拆成纯粹的“输入 -> 决策”函数和一个薄的副作用执行层。
   • 对多步骤异步行为，显式表示状态、事件和迁移；也可以运行真实状态模块，仅注入可控的边界依赖。
   • 网络、时钟、路由、存储、状态修改和通知只留在最外层。
5. 根据下表选择成本最低且足够可靠的测试层。
6. 先运行聚焦测试直至通过，再执行仓库要求的类型检查、格式化和完整测试。失败则修复后重试；无法执行的检查必须说明。
7. 完成需求实现与测试后，在最终回复中直接向开发者提交实施报告，不创建或修改报告文件；报告结构不限，如实覆盖完成内容、测试结果和未完成或未验证事项。

选择测试层

要验证的风险	测试层	保持真实	控制边界
业务分支、状态迁移或数据转换	单元测试	纯决策逻辑	仅输入
队列顺序、重试、竞态或恢复	状态模块测试	完整状态模块	执行器、时钟或存储边界
内部模块之间的契约	集成测试	所有协作的内部模块	网络、时钟或存储边界
无法下沉的跨系统黄金路径	E2E	UI 和必要的系统连接	优先使用有状态模拟后端

只有以下三项全部成立时才新增 E2E：

1. 行为跨越模块或系统边界。
2. 结果依赖外部世界在两次操作之间发生变化。
3. 抽出决策并验证低层契约后，仍有真实连接无法在 E2E 以下验证。

任意一项不成立，就把场景下沉到更低的测试层。

测试规则

• 断言可观察行为，不断言私有辅助函数或内部调用次数。
• 条件允许时，一个测试只覆盖一个决策分支。
• 真实运行内部模块，只模拟或注入外部边界。
• 只有时间需要控制时，优先使用 Vitest 等当前测试运行器的 fake timers；不要仅为测试 setTimeout 新增时钟接口或包装层。
• 如果时间之外的网络、随机数、ID、存储或进程通信也会改变结果，使用项目已有适配器，或增加覆盖本次改动所需的最小可替换边界。
• 不测试第三方库本身。
• 复杂结构化输出优先采用仓库认可的 inline snapshot，并审查生成的差异。
• 不要仅为了写测试，给无分支、无状态的简单包装函数增加抽象。

存量代码

不要发起大范围测试债务重构。需求触及旧代码时，只隔离并测试当前改变的决策。新代码遵循本方法，让覆盖率随着真实维护自然增长。覆盖率用于定位证据缺口，不代表代码一定正确。

参考资料

任务需要决策表、代码形态、评审清单、E2E 判断或存量代码恢复方式时，读取 references/methodology.md。

评估用例位于 evals/evals.json。

方法论来源：https://huali.cafe/post/frontend-testing-methodology/。