Back to Details

test-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Test-driven development (for agents)

测试驱动开发（适用于 Agent）

Prove intended product behavior with a failing test first, then make it pass with the smallest change. "Looks right" is not done.
先用一个失败的测试证明预期产品行为，然后以最小改动使其通过。“看起来没问题”并不代表完成。

Scope

适用范围

In scope (full cycle): features and bug fixes in app code; domain rules, mapping, validation, non-trivial helpers; HTTP / persistence / CRUD contracts; regression guards for bugs with a meaningful automated hook.
Out of scope (no new test; never add one that only mirrors a literal you set):
  • Docs, comments, formatting.
  • Mechanical moves / renames with unchanged behavior (still run the suites when code changed).
  • Declarative toolchain, build or dev-server config that flips an upstream option (bundler flag, lint rule, 
    tsconfig
    option).
  • Dependency bumps without logic changes; throwaway spikes (redo with the cycle before keeping them).
If unsure: in scope when the repo owns the logic or contract, out of scope when you only flip an upstream tool's switch.
适用范围内（完整执行流程）：应用代码中的功能和缺陷修复；领域规则、 映射、验证以及非平凡辅助函数；HTTP / 持久化 / CRUD 契约； 为缺陷添加且具备有效自动化钩子的回归防护。
适用范围外（不新增测试；绝不添加仅镜像所设字面值的测试）：
  • 文档、注释、格式调整。
  • 行为未变的机械式移动 / 重命名（代码变更后仍需运行测试套件）。
  • 切换上游选项的声明式工具链、构建或开发服务器配置（bundler 标志、lint 规则、
    tsconfig
    选项）。
  • 没有逻辑变更的依赖升级；一次性试验代码（保留前应重新按照该流程执行）。
如果不确定：仓库自身负责 逻辑或契约 时适用；仅切换上游工具开关时不在适用范围内。

Cycle (when in scope)

流程（适用时）

  1. Red: state the behavior in one sentence; write or extend a test; run it and confirm it fails for the right reason (not a compile error, bad import or flaky setup).
  2. Green: change production code just enough to pass. No drive-by refactors.
  3. Refactor: clean up with tests green.
If no meaningful failing test can be written, clarify the requirement instead of writing code or a hollow test.
  1. Red：用一句话说明行为；编写或扩展测试；运行测试并确认其因正确原因失败（而不是编译错误、错误导入或不稳定的测试环境）。
  2. Green：仅修改必要的生产代码，使测试通过。不进行顺带重构。
  3. Refactor：在测试保持通过的情况下整理代码。
如果无法编写有意义的失败测试，应先澄清需求，而不是直接编写代码或空洞的测试。

Layer

层级

  • Discover the project's test docs (
    docs/testing.md
    , 
    AGENTS.md
    ) and copy a nearby test's style, naming and location.
  • Pick the lowest layer that locks the behavior; one focused test beats several overlapping ones. End-to-end only for user-visible integration.
  • Prefer real collaborators over mocks when a lower layer expresses the contract cleanly.
  • Verify behavior with automated tests. When the contract is page structure, assert it through the project's test runner. A check that only a person can judge by looking stays outside this cycle.
  • 查找项目的测试文档（
    docs/testing.md
    、
    AGENTS.md
    ），并沿用附近测试的风格、命名和存放位置。
  • 选择能够锁定该行为的最低层级；一个聚焦的测试优于多个相互重叠的测试。仅在用户可见的集成场景中使用端到端测试。
  • 如果较低层级能够清晰表达契约，应优先使用真实协作者而非 mock。
  • 使用自动化测试验证行为。当契约涉及页面结构时，通过项目的测试运行器进行断言。只能由人员通过肉眼判断的检查不属于该流程。

Running

运行

Use the project's scripts (
package.json
, 
Makefile
, 
AGENTS.md
). Run focused tests on each Red / Green step; before finishing run the full suites (or the project's single finish / verify command) when product code changed, or the smallest relevant check for out-of-scope config. Not done until they pass.
使用项目的脚本（
package.json
、
Makefile
、
AGENTS.md
）。在每个 Red / Green 步骤运行聚焦测试；完成前，如果产品代码发生变更，则运行完整测试套件（或项目唯一的完成 / 验证命令）；对于适用范围外的配置，则运行最小相关检查。测试未通过前不算完成。

Do not

禁止事项

  • Implement first, then write a test that mirrors the code.
  • Assert a config flag equals the value you just set.
  • Change a test to match buggy behavior without a product decision.
  • Churn unrelated tests or snapshots.
  • Use e2e as a substitute for a unit test of a pure helper.
  • Leave Red unobserved, tests failing, or finish on focused runs alone.
  • 先实现，再编写一个镜像代码行为的测试。
  • 断言配置标志等于刚刚设置的值。
  • 未经产品决策就修改测试以适配有缺陷的行为。
  • 无谓地改动无关测试或快照。
  • 使用 e2e 替代对纯辅助函数进行单元测试。
  • 放任 Red 阶段未被观察、测试失败，或仅完成聚焦测试就结束工作。