nexmoe-best-practices-testing

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Nexmoe 测试最佳实践

测试的证据是用户获得的结果。业务行为不变时，重命名、拆函数、换内部调用顺序不应让测试失败。

## 1. 先写验收场景，再实现

- 在修改业务代码前，根据需求写出验收场景和预期结果；不得从刚写好的实现反推预期值。
- 所有测试场景描述以小写 `user ` 开头，包括参数化测试展开后的描述。描述用户行为及结果，避免函数名和内部步骤；测试套件标题也遵循此约定。
- 用 **Given / When / Then** 依次说明已知条件、用户操作、可观察结果。先写场景时可使用场景文件；Viora 的可执行测试必须在回调内保留有内容的对应注释或 `test.step`，供 lint 检查。每部分都应让用户和 PM 能看懂。
- 先写可执行的验收测试，运行并确认它因预期行为缺失而失败，再实现、通过、重构。环境、编译或数据准备失败不算有效的红灯。
- 为已有正确行为补测试时，允许首次就通过；明确这是补证据，不伪称经历了红灯。修 bug 则先复现旧行为失败。

```gherkin
Scenario: user 重复提交同一订单只会被扣款一次
  Given 用户余额为 100 元，待支付订单金额为 20 元
  When 用户提交支付后重试同一订单
  Then 用户余额为 80 元，订单显示已支付，账单只有一笔 20 元的扣款

Scenario: user 支付失败后仍能重试且不会丢失余额
  Given 用户余额为 100 元，待支付订单金额为 20 元，支付服务明确拒绝本次支付
  When 用户提交支付
  Then 用户看到可重试的失败结果，余额仍为 100 元，订单没有被标记为已支付
```

## 2. 只断言行为和契约

- 从用户入口触发操作，检查页面可见状态、公开响应、账单、持久化结果等业务证据。API 或 CLI 的使用者也是 user。
- 不断言私有方法调用次数、内部调用顺序、组件内部 state、Tailwind class 或 CSS 变量；“没有重复扣款”要验证账单和余额，不能用“支付方法调用一次”代替。样式相关改测可访问性属性、语义状态或 reduced-motion 契约。
- 不用源码字符串、常量互相比对、巨型快照或 mock 回声证明业务正确；常量相关改测派生不变量或 locale 等集合的完整性契约。协议 fixture、manifest、构建产物或 lint 自身的语法输入可以直接检验格式，因为格式就是这些边界的行为。
- 不以 `toBeDefined`、`toBeTruthy`、`not.toThrow`、`length > 0` 等宽泛断言充当验收结论；断言关键值、确切状态或有意义的不变量。
- 覆盖场景需要的成功、失败、边界、重试、并发与权限行为，按实际风险选择，不为每个实现分支机械复制测试。
- 每个 e2e 文件必须带 surface tag，进入明确的运行选择面。
- 文案 lint 不算行为测试；竞品名、禁用词等归内容检查脚本。
- 本节和第 3 节的例外必须在测试名或注释中写明所保护的具体 bug。

## 3. 禁止 mock；真实依赖优先

- 禁止模块 mock、函数 mock、spy、调用记录断言和 monkey patch；不得换个名字将其包装成 fake。测试工具的通用 mocking 示例不构成例外。
- Redis、PostgreSQL 等可本地运行的依赖使用真实服务和真实查询。用隔离数据库、schema 或 key 前缀准备及清理数据，等待健康状态，保证并行测试互不污染。不要用内存 Map 假装验证数据库事务或锁。
- 外部系统难以接入时，在外部边界注入 **fake**：它实现实际需要的状态转换、错误和协议行为，不替换被测业务逻辑，也不只返回测试指定的答案。
- 对真实适配器和 fake 运行同一组契约场景，核对请求/响应、错误语义、幂等性及相关状态变化。类型通过或 fixture 能解析不等于契约验证；记录真实系统的版本、验证命令和结果。
- 真实系统暂不可达时，报告契约未验证及受影响场景；不能把 fake 测试通过报告成真实集成通过。
- 时间逻辑用 fake timer 或注入时钟，测试后恢复。它们属于明确允许的时间控制；不要扩大为允许业务 mock。跨进程 E2E 要控制真正持有计时逻辑的进程。
- 禁止用 sleep、固定延时或 `waitForTimeout` 同步。等待可见状态、事件或带截止时间的条件轮询；时间边界通过推进受控时钟验证。

## 4. 大部分测试采用 E2E，按影响范围执行

- 默认从真实用户入口走过应用的主要处理链路到可见结果；外部依赖可用上述 fake，应用内部业务链路与可用的存储保持真实。
- E2E 确实不适合表达的算法组合、协议细节或难以从用户入口稳定触发的边界，可补契约、集成或单元测试。说明不适合的具体原因；“纯函数能测”本身不是放弃用户验收的理由。
- 不设 E2E 数量配额，不为占比重复测试同一行为。以关键用户路径的证据为主，底层测试补充具体缺口。
- 分级为静态检查、关键路径 smoke、受影响场景、完整回归。依据改动及依赖关系选择测试，包含共享代码、配置、数据 schema、fixture 和 fake 的消费者；无法确定影响范围时扩大执行。
- 日常改动运行相关层级，固定周期执行完整回归，发布前按风险补全。不要每改两行就跑全部，也不能永远只跑受影响子集。

## 5. 场景质量合格后，检查 70% 分支覆盖率

- 分支覆盖率门槛为 **70%**。对声明的生产代码范围统计，纳入未被任何测试导入的文件；不能只统计命中的文件或新增行。
- E2E 与底层测试的覆盖数据若可合并，应来自同一代码版本并正确映射到源码；不能假设浏览器覆盖率包含服务端或其他进程。
- 逐项解释未覆盖分支，优先检查失败、超时、回滚、重试、权限拒绝和降级路径。70% 通过不代表余下 30% 自动可接受，关键失败路径不能被总数掩盖。
- 不得为了达标新增无业务意义的断言、再降低阈值、缩小统计范围、加忽略标记或跳过测试。缺口应补有意义的场景；确实无法验证时如实报告缺口与风险。

## 6. 能确定判定的规则必须自动化

- 优先在现有 lint 和验证入口增加规则，避免另起一套不运行的检查。实施规则时先写违规及合规输入的验收样例，再实现检测。
- 自动检查 `user ` 前缀、Given / When / Then 的存在与顺序、mock/spy、调用细节断言、固定等待、聚焦/无条件跳过、空洞断言、E2E 选择标签等。
- 使用 AST 和导入绑定识别测试代码，覆盖别名及参数化语法；注释、字符串中的示例不得误报。时间控制必须有合规用例，不能因工具名称含 mock 一并封禁。
- 分支覆盖率使用运行时覆盖率门禁；fake 契约使用真实契约测试。lint 只能检查可确定的结构，不能证明用户价值、场景先于实现或 fake 等价性。
- 历史违规需显式记录并逐步收敛，新测试和新增违规不能用全局关闭规则绕过；不要借制定规范之机全仓重写旧测试。
- 在 Viora 中落地 lint 或选择验证命令时，阅读 [测试治理与 lint 清单](../../../docs/operations/behavior-testing.md)。运行 `pnpm run check:governance`；修复历史违规后用 `pnpm run check:governance --prune-baseline` 收敛记录。不得重建或扩大历史基线来通过检查。

## 交付证据

简要说明验收场景、测试层级及选择理由、真实依赖和 fake 契约状态、运行命令与结果、分支覆盖率及未测原因。未执行、环境失败和契约未验证必须与通过分开陈述。不要以 lint 通过代替行为验收。

From nexmoe/skills, MIT.

More from nexmoe/skills