SuperAPI AI 工具集

write-a-spec

测试与质量

查看项目

更新于 10-15 21:10

技能介绍

用途:在 evals/specs 下编写或扩展 journey spec。仅在覆盖决策表明某个 journey spec 缺少断言,或出现新的用户旅程时才使用。

不适用情形:已有 journey spec 覆盖该行为时应扩展而非新建;纯函数改动应写同目录单元测试;若需要导入 ../../apps|packages|ee、读取源文件或启动其他测试运行器,则属于伪装的单元测试,会被边界约束拒绝。每个用户旅程一个 spec,而非每个 PR 一个;缺陷修复应在其逃逸的旅程中增加断言。

用法:新测试写在 evals/specs/**/*.test.ts,并从 @openwork/testkit 导入 test。驱动应用的 E2E 测试使用 .e2e.test.ts,PR 通道会排除它们。按依赖顺序将模型建模为资源:needs() → server() → app()。

testkit 原语:server() 启动或复用 Den 并配置隔离组织;app() 启动已登录桌面端,profileDir 用于调用方拥有的 profile 连续性,localServerDelayMs 用于确定性的启动竞态;inviteMember() 向已有 Den 添加具名成员;faultProxy() 注入 faults.status() 或 faults.latency(),并暴露 requests 日志以断言尝试与恢复;eventually() 限定轮询并报告最后的值或错误;readDenClientState()、readConnectState()、readConnectStateFile() 暴露客户端、本地服务器与持久化 profile 状态。

断言与见证:每个声明都需可机器校验,包含可观察断言及其显式反面,同时断言预期效果与不得对其他身份、账户、请求、文件或状态发生的事。散文不是证明,截图可解释断言但不能替代。描述产品行为而非偶然布局。声明需与产品屏幕实际表述一致,若分歧应显式修改其一。不得把答案偷带进提示,需断言面向用户的请求不包含连接器或资源 ID。

Mock:使用 mcpMock() 见证,绝不在 spec 中调用真实提供方。见证位于 evals/packages/labs/src/,遵循 mock-mcp.ts 与 provider 专属 mock-*.ts 夹具,保持确定性、身份限定且可查询。

证据契约:测试证据是环境性的,screenshot() 记录截图产物,validate() 记录其视觉校验(无论通过与否),recordAssertionEvidence() 保存见证断言。不得在测试体内创建或传递测试证据记录器句柄。为每个等待设定边界。在 needs() 中声明所有外部需求,使缺失依赖大声跳过而非超时或削弱覆盖。