test-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Test It

Make the intended behavior provable with automated and/or explicit manual evidence. Discover the repo's real test stack; do not invent a new framework unless asked.

Name the quality regime first (see handbook

concepts/11-quality-regimes.md

Regime	Prove with…
A — Deterministic compute (API/algo/analytics)	Invariants, golden/property tests, data contracts / expectation suites
B — Interactive product (web/fullstack)	Behavior tests + critical E2E; a11y; performance budgets / Web Vitals where relevant
C — Generative / high-input	Datasets + layered graders (code → LLM-judge → human); not exact free-text equality. Prefer Langfuse (or repo OTel eval stack) for experiment scores

Hybrids: gate each surface by its own regime.

通过自动化和/或明确的手动证据，让预期行为可被验证。先探明仓库实际使用的测试技术栈；除非用户要求，否则不要发明新的测试框架。

请首先明确质量体系（参见手册

concepts/11-quality-regimes.md

）：

体系	验证方式…
A — 确定性计算（API/算法/分析）	不变量、金标准/属性测试、数据契约 / 预期套件
B — 交互产品（Web/全栈）	行为测试 + 关键E2E；a11y；相关场景下的性能预算 / Web Vitals
C — 生成式/高输入	数据集 + 分层评分器（代码 → LLM-judge → 人工）；不要求自由文本完全一致。实验评分优先使用Langfuse（或仓库的OTel评估栈）

混合场景：每个层面按其对应的体系设置门禁。

Operating contract

运行契约

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's
```
Workflow
```
tool only for orchestration across many subagents that truly needs it; it is expensive.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code
```
CLAUDE_CODE_SUBAGENT_MODEL
```
or a CLAUDE.md rule; Codex
```
agents.default_subagent_model
```
or a role's
```
agents.<name>.config_file
```
; Cursor a custom subagent's
```
model:
```
frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code
```
haiku
```
); implementation and evidence gathering → mid (
```
sonnet
```
); planning, review, adversarial verification → top (
```
opus
```
or
```
fable
```
). In Claude Code set it with the
```
Agent
```
tool
```
model
```
param or agent frontmatter
```
model:
```
; in Codex pass a spawn model or set
```
model
```
in the role's config file; in Cursor set
```
model:
```
(default
```
inherit
```
) in
```
.cursor/agents/*.md
```
. Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

所有DecisionNerd/dev-skills技能共享。规范副本：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。 在使用工具之前，用一两句话写下终点：验收标准（如果存在现有issue的AC、BDD场景、测试或契约，则使用这些；否则提出验收标准并说明应存放的位置）以及验证这些标准的证据。在报告完成前重新检查。永远不要对未验证的工作报告完成。
请求的范围决定终点。 问题类请求（“准备好了吗？”、“为什么坏了？”、“下一步是什么？”）以答案和一行明确指定下一个调用的
```
Next:
```
结尾。结果类请求（“修复”、“完成”、“上线”、“#42”）会沿着链路持续推进（诊断 → 修复 → 测试 → 就绪检查 → 合并）直到达成结果或遇到真正的阻塞。对于范围内、仓库内的工作，不要以“你需要我…吗？”结束一轮交互。
仅在遇到真正阻塞时停止。 只有在没有用户参与就无法继续时，或者在以下操作之前才停止并询问：删除数据或未合并的工作、强制推送或历史重写、修改本仓库之外的任何内容（GitHub对象、部署、实时数据、生产或付费资源、外部服务），或者超出请求范围——除非用户的请求已经明确指定了该操作。对于风险命令，保留工具框架的权限提示。否则继续推进，并将状态说明与下一步操作放在同一条消息中。
一次问清楚，问到位。 对于真正的问题，如果工具有结构化提问工具（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时使用
```
request_user_input
```
），则使用该工具并提供具体选项；否则使用带编号选项的纯文本。将答案视为最终决定；除非被要求，否则不要重新讨论之前的结论、计划或答案。
可并行工作时拆分任务。 对于独立的读取类任务（仓库调研、证据收集、各选项研究、各领域审计）和独立验证（未编写变更的评审者），使用子Agent。写入类操作按路径集保持单一负责人且顺序执行。向每个子Agent说明目标、完成条件、约束、禁止事项和返回格式；在整合前验证每个子Agent的结果。仅在确实需要编排大量子Agent时才使用Claude Code的
```
Workflow
```
工具；该工具成本较高。
为每个子Agent选择模型等级；遵循路由配置。 如果工具框架或用户配置已经为子Agent设置了路由（Claude Code的
```
CLAUDE_CODE_SUBAGENT_MODEL
```
或CLAUDE.md规则；Codex的
```
agents.default_subagent_model
```
或角色的
```
agents.<name>.config_file
```
；Cursor自定义子Agent的
```
model:
```
前置元数据），则遵循该配置，不要传递模型参数。否则：机械搜索或盘点 → 快速/低成本（Claude Code
```
haiku
```
）；实现和证据收集 → 中等（
```
sonnet
```
）；规划、评审、对抗性验证 → 顶级（
```
opus
```
或
```
fable
```
）。在Claude Code中，通过
```
Agent
```
工具的
```
model
```
参数或Agent前置元数据的
```
model:
```
设置；在Codex中，传递生成模型或在角色配置文件中设置
```
model
```
；在Cursor中，在
```
.cursor/agents/*.md
```
中设置
```
model:
```
（默认
```
inherit
```
）。如果工具框架无法选择，子Agent将继承父模型或由工具框架选择（Cursor内置的Explore/Bash/Browser子Agent会按子任务选择）；在状态说明中说明使用的模型。
长时间运行时保留检查清单。 对于超过约五个步骤或跨技能的工作，在仓库根目录维护
```
TASKS.md
```
，完成一项就勾选一项。除非仓库已经跟踪该文件，否则不要提交它。
每次运行结束时包含三个标题。
```
Blocked on me
```
（一个真正的问题或阻塞，否则为“none”）；
```
Changed
```
（文件、提交、GitHub对象、部署，否则为“nothing”）；
```
Found
```
（证据、结论以及
```
Next: <具体调用>
```
）。

When to use

适用场景

"Add tests", "cover this", "test it", failing CI, flaky specs, eval harness gaps

After

fix-it

diagnose-bug

troubleshoot-app

agents optimize

when verification is missing

Before
```
check-readiness
```
or
```
merge-it
```
when BDD/eval scenarios lack evidence

“添加测试”、“覆盖该场景”、“test it”、CI失败、不稳定测试用例、评估工具缺口

在

fix-it

diagnose-bug

troubleshoot-app

agents optimize

之后，缺少验证时

在
```
check-readiness
```
或
```
merge-it
```
之前，BDD/评估场景缺少证据时

When NOT to use

不适用场景

Behavior change disguised as "refactoring tests" → fix the product with
```
fix-it
```
, then cover
Scaffolding a new test framework "for completeness" without user ask
Using unit-test green to claim chat/agent quality (regime C needs evals/scores)

伪装成“测试重构”的行为变更 → 使用
```
fix-it
```
修复产品，然后再覆盖测试
未经用户要求，“为了完整性”而搭建新的测试框架
用单元测试通过来宣称聊天/Agent的质量（C体系需要评估/评分）

Workflow

工作流

Done when: named scenarios map to tests, the narrowest suite passes, nothing claimed green that wasn't run. Fan out per test layer (unit / integration / e2e) when files don't overlap — one subagent per layer (mid tier); single writer per path set.

Name the regime (A / B / C / hybrid) and the oracle you can actually check.
Scope the contract
- From issue/PR/BDD scenarios, failing assertion, eval dataset, or user-stated behavior.
- Prefer existing Given/When/Then, test names, or dataset items over inventing parallel specs.
Discover harness
- ```
package.json
```
  /
```
Makefile
```
  / CI /
```
pytest
```
  /
```
cargo test
```
  / eval runner / Langfuse datasets / etc.
- Note unit vs integration vs e2e vs eval commands and how CI invokes them.
- No test framework found: ask with options via the question tool before adding one.
Choose the smallest layer that proves the bug/feature
- Regime A: pure logic → unit/property; DB/API → integration; pipeline → golden/correctness checks
- Regime B: component behavior → integration; user journeys → e2e; a11y/perf budgets as earned
- Regime C: offline dataset experiment → CI score gate; promote production failures into the suite
- External systems without sandbox → document manual evidence + why
Implement or fix tests / evals
- Match local patterns (fixtures, factories, MSW, Playwright, graders, etc.).
- Cover failure mode + success path + one boundary (authz, empty, overflow, jailbreak/injection for C).
- Stabilize flakes: freeze time/seed, remove order dependence, await deterministically; for C, multi-trial stats when needed.
Run and report
- Run the narrowest command that validates the change.
- Map each BDD/eval scenario → test file, score, or manual evidence note.
- Do not claim green if you did not run (or could not run) the relevant suite.
Wrap up
- Next:
```
check-readiness
```
  (run it when in a completion chain);
```
pulls refine
```
  for a test plan;
```
observe-it
```
  / Langfuse for online eval coverage;
```
merge-it
```
  to land.

完成条件：指定的场景都映射到测试，最小范围的测试套件通过，未运行的测试绝不宣称通过。当文件不重叠时，按测试层（单元 / 集成 / e2e）拆分任务——每层一个子Agent（中等模型等级）；每个路径集只有一个写入者。

明确体系（A / B / C / 混合） 以及你实际可以验证的判定依据。
界定契约范围
- 来源包括issue/PR/BDD场景、失败的断言、评估数据集或用户说明的行为。
- 优先使用现有的Given/When/Then、测试名称或数据集项，而不是发明并行的规范。
探明测试工具链
- ```
package.json
```
  /
```
Makefile
```
  / CI /
```
pytest
```
  /
```
cargo test
```
  / 评估运行器 / Langfuse数据集 / 等。
- 记录单元、集成、e2e、评估的命令，以及CI如何调用它们。
- 未找到测试框架：在添加之前，通过提问工具提供选项进行询问。
选择能验证bug/功能的最小测试层
- A体系：纯逻辑 → 单元/属性测试；数据库/API → 集成测试；流水线 → 金标准/正确性检查
- B体系：组件行为 → 集成测试；用户旅程 → e2e；按需添加a11y/性能预算
- C体系：离线数据集实验 → CI评分门禁；将生产环境的失败案例加入测试套件
- 无沙箱的外部系统 → 记录手动证据 + 原因说明
实现或修复测试 / 评估
- 遵循本地模式（fixtures、factories、MSW、Playwright、评分器等）。
- 覆盖失败模式 + 成功路径 + 一个边界场景（C体系包括authz、空值、溢出、越狱/注入）。
- 稳定不稳定测试：冻结时间/随机种子，消除顺序依赖，确定性等待；对于C体系，必要时使用多次试验统计。
运行并报告
- 运行能验证变更的最小范围命令。
- 将每个BDD/评估场景映射到 → 测试文件、评分或手动证据说明。
- 如果你没有运行（或无法运行）相关测试套件，不要宣称通过。
收尾
- 下一步：
```
check-readiness
```
  （在完成链路中运行）；测试计划使用
```
pulls refine
```
  ；在线评估覆盖使用
```
observe-it
```
  / Langfuse；合并上线使用
```
merge-it
```
  。

Guardrails

护栏规则

No drive-by refactors while testing unless required for testability (prefer
```
refactor-it
```
).
Don't delete coverage to "make CI green" without an explicit waiver.
Redact secrets in fixtures and snapshots.

测试期间不要顺手重构，除非是为了可测试性（优先使用
```
refactor-it
```
）。
没有明确豁免的情况下，不要为了“让CI变绿”而删除覆盖率统计。
对fixtures和快照中的敏感信息进行脱敏处理。

Output

输出格式

markdown

**Contract**
- ...

**Harness**
- Commands: ...

**Changes**
- Tests added/updated: ...
- Scenario → evidence map: ...

**Results**
- Ran: <command> → <pass/fail>
- Not run: <why>

markdown

**Contract**
- ...

**Harness**
- Commands: ...

**Changes**
- Tests added/updated: ...
- Scenario → evidence map: ...

**Results**
- Ran: <command> → <pass/fail>
- Not run: <why>

Blocked on me

none

Changed

Found

...
Next: check-readiness / merge-it

undefined

...
Next: check-readiness / merge-it

undefined

Grounding

参考依据

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook

sources.md

Quality is regime-specific (

handbook/concepts/11-quality-regimes.md

) and traced through DocSlime + lightweight BDD (

13-quality-trace.md

): pyramid + contracts for compute; journeys/a11y/Web Vitals for products; datasets + layered graders for generative. Prefer existing REQUIREMENTS/TESTING/issue scenarios over inventing frameworks.

Handbook card:

handbook/practices/test-it.md

本技能的TTPs基于当前工程基线（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis —— 参见手册

sources.md

）。

质量是分体系的（

handbook/concepts/11-quality-regimes.md

），通过DocSlime + 轻量级BDD进行追溯（

13-quality-trace.md

）：计算类使用金字塔模型 + 契约；产品类使用用户旅程/a11y/Web Vitals；生成式类使用数据集 + 分层评分器。优先使用现有的REQUIREMENTS/TESTING/issue场景，而不是发明新框架。

手册卡片：

handbook/practices/test-it.md

。