SuperAPI AI 工具集

test-quality

测试与质量

查看项目

更新于 10-27 16:20

技能介绍

用途

Test Quality 是一套与测试框架无关的工程技能,用来判断单个自动化测试是否值得保留:它断言什么、如何命名与组织、伪造了什么、是否每次运行结果一致。规则适用于任意运行器(Vitest、Jest、node:test)和任意框架,示例使用 TypeScript。

该技能建立在 core-typescript(测试代码也是代码)、architecture-and-design 的测试套件策略(测试金字塔、单元测试与集成测试),以及 react / angular / vue 的组件渲染与查询机制之上。只有当任务涉及某一层时才加载对应技能;若未加载,则用通用知识应用该层,不要阻塞。

SKILL.md 自身是自足的:其中的 Ruleset 是完整、可执行的清单。每个 references/<topic>.md 保存该组的推理与 ❌ / ✅ 代码,references/worked-example.md 提供一次完整评审示例;在运行环境允许时可打开以获取更多细节。

主要能力

技能提供四种使用模式,按顺序执行步骤:

  • Write——为新代码或变更代码添加测试:为每个公开行为命名场景与预期结果(structure-and-naming);通过公开 API 进行 Arrange,一次调用完成 act,对可观察结果断言(behavior-not-implementation、assertions);用 builder 构造输入,只按 test-doubles 允许的方式伪造;每个新测试先跑一次红灯(针对未修复代码或故意破坏的行),再信任绿灯;最后把 Ruleset 当清单逐项检查并修复。
  • Review——检查拉取请求中的测试:对测试 diff 运行 Ruleset;每个失败写一条 finding,按输出格式;先 must-fix 后 consider;若无失败,用一行说明,不要编造问题。
  • Triage——修复薄弱、脆弱或不稳定的测试:指出它为何不好(断言内部实现、没有真实断言、依赖顺序、非确定性);改测试而非被测代码,除非测试发现了真实 bug;立即隔离 flake,并在本迭代内修复,而不是靠 CI 重试。
  • Characterize——在改动未测试代码前先加测试:编写固定当前可观察行为(包括怪癖)的测试,先不修 bug;对未改动代码跑绿,作为安全网;在安全网后重构或修复,只有故意改变该行为时才更新特征测试。

使用方式

输出格式为每行一条 finding:

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.

其中 <severity> 为 must-fix(违反本技能规则)或 consider(安全,但规则更偏好另一种形式);<topic> 为 Ruleset 主题 slug(assertions、test-doubles、determinism 等)。

判断测试是否值得保留,看四个相互权衡的属性:回归保护(真实行为破坏时会失败)、抗重构(内部变化但行为不变时保持绿色)、快速反馈(毫秒级运行,可每次保存都跑)、可维护性(下一位读者能理解并低成本修改)。两项得分低的测试是负债:断言实现会牺牲抗重构;真实 I/O 会牺牲快速反馈且常牺牲保护(flake);巨大的共享 fixture 会牺牲可维护性。

所有模式通用规则:执行规则时点明 Ruleset 主题;说明原因而不只是规则;点明规则与改动,不要默默重写作者的测试;测试存在的意义是捕获用户能感受到的回归;当测试与代码不一致时,先弄清谁对再改任何一方。

Ruleset 主题

  • behavior-not-implementation:断言可观察输出(返回值、渲染结果、发布的消息、持久化记录),绝不断言私有字段或内部步骤;不把协作者调用次数/参数当作效果检查的替身,除非调用本身即契约(分析事件、发送邮件);只引用单元公开 API;不 spy 或部分 mock 被测系统;通过公开构造器、工厂或 API 布置状态;能经受保持行为的重构,行为改变时会失败;不测试你不拥有的框架/库/语言特性;被测单元是行为单元而非单个类;私有方法通过公开 API 行使,复杂到需要单独测试时应提取为独立单元。
  • assertions:每个测试至少一个断言;一个测试一个行为;使用具体匹配器(toEqual(3) 优于 toBeTruthy(),toThrow(SpecificError) 优于 toThrow());断言检查整个相关结果;仅当顺序是契约一部分时才按有序列表比较集合;不用与被测代码相同逻辑计算出的值做断言;错误路径断言错误类型或消息;异步测试 await 结果并在 settle 后断言;快照要小、稳定、每次变更都审查。
  • structure-and-naming:测试名说明场景与预期结果,而非方法名;Arrange / act / assert 视觉上区分,act 为单次调用;测试体内无生产逻辑;重复用例用数据驱动表(it.each);beforeEach 只放文件内每个测试都需要的设置;不依赖执行顺序或前一测试留下的状态;不提交 .only / fit / fdescribe,.skip / xit 需在注释中附跟踪工单。
  • test-data:用工厂或 builder 填充合理默认值,测试只设置被测字段;断言依赖的值在测试中可见;避免许多测试以冲突方式依赖的大型共享 fixture;随机数据需种子化并在失败时打印;不同角色用不同值。
  • test-doubles:只有因慢、非确定性、有副作用或尚不存在时才用替身;网络在边界处打桩(MSW、假服务器),而非 mock 自己的模块;许多测试共用的协作者优先用 fake(可工作的内存实现)而非脚本化期望的 mock;手写 fake 需有契约测试同时跑 fake 与真实实现;绝不被测类型本身;stub 返回满足协作者契约的真实值;测试间重置 mock;时间、随机、文件系统、环境变量注入或伪造。
  • determinism:单元测试不做真实 I/O;不用真实 sleep 或任意超时;控制时钟与随机;不依赖真实网络、墙钟日期、locale 或时区;测试可任意顺序并行通过;清理放在 afterEach 且失败时也运行。
  • coverage:覆盖率是未验证之处的映射而非要达成的分数;测试分支与边界;关键逻辑(金钱、认证、权限、迁移)在边界处检查,必要时做变异测试;不写只为提高数字的测试。

适用场景

适用于编写新测试、评审 PR 中的测试、修复薄弱/脆弱/flaky 测试,以及在改动未测试代码前建立特征测试。

限制

本技能只评判单个测试,不覆盖:测试套件策略与测试金字塔(属于 architecture-and-design 的 testing 组);框架机制(React Testing Library、Angular TestBed、Vue Testing Library 等,属于 react / angular / vue 的 testing 组);端到端测试设计(Playwright、Cypress,属于 e2e-testing);性能与负载测试;无障碍测试(完整视角在 accessibility);运行器选择与配置及 CI 并行化。本技能说明什么使测试值得保留,不能替代实际运行测试套件并阅读真正失败的内容。