用途
write-tests 用于为已有的源代码添加或改进测试覆盖率,且明确要求不修改生产代码、不改变生产行为。它只负责编写测试,生产行为被视为固定不变。
主要能力
该技能的核心能力是根据模块类型选择对应的 mock 策略,而不是套用统一的 mock 模式。资料中给出的模块类型与策略对应关系如下:
- 路由处理器(Route handler):使用测试应用构建器、会话模拟以及 app.inject()。
- 仓库层(Repository):mock 数据库连接,并使用基于计数器的 execute。
- 框架插件(Framework plugin):使用真实框架实例,并对依赖进行选择性 mock。
- 纯工具函数(Pure utility):不使用 mock,直接测试输入与输出。
- 带依赖注入的服务(Service w/ DI):通过转发模式 mock 注入的依赖。
此外,技能还包含一组明确的禁止事项,用于规避常见错误:
- 在 mockReset: true 时,禁止链式使用 mockResolvedValueOnce,因为链会在测试之间被清除;应改用基于计数器的 mockImplementation。
- 禁止在模块作用域定义 mock 变量后在 vi.mock() 工厂中引用,因为变量提升会造成暂时性死区;应使用 vi.hoisted() 或 globalThis 注册表。
- 禁止对有副作用的模块使用 vi.importActual(),应改用选择性重新导出。
- 禁止测试实现细节(私有状态、内部调用顺序),应通过公共 API 测试可观察行为。
- 禁止从其他项目复制 mock 模式,应先检查自己的测试运行器配置(mockReset、mockClear、restoreMocks)。
- 禁止修改源代码。
使用方式
在编写测试前,技能要求先自问几个问题:模块类型是什么、影响范围(blast radius)如何、是否存在需要隔离的副作用(数据库写入、API 调用、文件系统)、最近的测试文件在哪里。它建议找到最近的 *.test.ts 并匹配其确切的 mock 结构,而不是发明新模式。
对于使用 mockReset: true 的测试运行器,资料给出了具体的 mock 设置示例:使用 vi.hoisted() 创建 mock 函数,在 vi.mock() 中通过转发函数引用它,并在 beforeEach 中重新配置返回值,因为 mockReset 会在测试之间清除返回值。对于多个相互依赖 mock 的复杂暂时性死区情况,可使用 globalThis 注册表模式。
运行命令为:
npx vitest run <test-file> --reporter=verbose
参数 $ARGUMENTS 为待覆盖的源文件或模块路径,例如:
/write-tests src/routes/admin/settings.ts
如果参数为空,则询问用户哪个文件需要测试覆盖。
适用场景
适用于已有源代码需要补充或改进测试覆盖率、且不希望改动生产行为的场景。尤其适合需要按模块类型区分 mock 策略的项目,以及使用 vitest 且配置了 mockReset: true 的测试环境。
限制
该技能只编写测试,不修改源代码。资料中未提供关于收费、价格、平台支持范围、具体效果保证等信息。资料中提到的元认知规则指出:如果首次运行时有超过 3 个测试失败,应停止逐个修复,因为根因很可能是影响所有测试的 mock 接线问题,需要整体重新检查 mock 设置。