Test-Driven Development

测试驱动开发

Philosophy

核心理念

Core principle: Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests should not.

Good tests are integration-style: they exercise real code paths through public APIs. They describe what the system does, not how. A good test reads like a specification. These tests survive refactors because they don't depend on internal structure.

Bad tests are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means. Warning sign: your test breaks when you refactor, but behavior hasn't changed.

See reference/tests.md for examples and reference/mocking.md for mocking guidelines.

核心原则：测试通过公共接口验证行为，而非验证实现细节。代码可以完全重构，但测试不需要改动。

优秀的测试是集成风格的：它们通过公共API覆盖真实代码路径，描述系统「做什么」而非「如何实现」。好的测试读起来就像一份需求规范，这类测试在重构时不会失效，因为它们不依赖内部结构。

糟糕的测试与实现逻辑耦合：它们会mock内部依赖、测试私有方法，或是通过外部手段验证结果。警示信号：你重构代码时功能行为没有变化，但测试却失败了。

查看 reference/tests.md 了解示例，查看 reference/mocking.md 了解mock规范。

Framework Agnostic

框架无关

This skill works with any test framework (Vitest, Jest, Playwright, Cypress, pytest, JUnit, etc.) and any stack (Vue.js, React, Node.js, backend services). Adapt examples to the project's language and framework.

该方法适用于所有测试框架（Vitest、Jest、Playwright、Cypress、pytest、JUnit等）和所有技术栈（Vue.js、React、Node.js、后端服务等），可根据项目的语言和框架调整示例。

Anti-Pattern: Horizontal Slices

反模式：水平切片

DO NOT write all tests first, then all implementation. This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."

This produces poor tests: they test imagined behavior, test the shape of things rather than user-facing behavior, and become insensitive to real changes.

Correct approach: Vertical slices via tracer bullets. One test, one implementation, repeat.

WRONG (horizontal):
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

RIGHT (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3

切勿先编写所有测试，再编写所有实现代码。 这就是「水平切片」——把RED阶段等同于「编写所有测试」，把GREEN阶段等同于「编写所有代码」。

这种做法会产出质量低下的测试：它们测试的是「设想中」的行为、验证的是结构形态而非面向用户的实际行为，对真实的功能变化不敏感。

正确做法：通过示踪弹实现垂直切片。一次写一个测试，对应实现一次功能，循环往复。

WRONG (horizontal):
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

RIGHT (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3

Workflow

工作流程

1. Planning

1. 规划

Before writing any code:

Confirm with user what interface changes are needed
Confirm which behaviors to test (prioritize — you can't test everything)
Identify opportunities for deep modules (small interface, deep implementation)
Design interfaces for testability
List behaviors to test (not implementation steps)
Get user approval on the plan

Ask: "What should the public interface look like? Which behaviors are most important to test?"

在编写任何代码前：

与用户确认需要改动的接口
确认需要测试的行为（做好优先级排序——你不可能测试所有场景）
找出可实现深度模块的机会（小接口，深实现）
设计具备可测试性的接口
列出需要测试的行为（而非实现步骤）
让用户确认规划方案

可询问：「公共接口应该是什么样的？哪些行为是最需要测试的？」

2. Tracer Bullet

2. 示踪弹验证

Write ONE test that confirms ONE thing — proves the path works end-to-end:

RED:   Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes

编写一个测试来验证一项行为——证明端到端路径可正常运行：

RED:   Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes

3. Incremental Loop

3. 增量循环

For each remaining behavior:

RED → GREEN

, one test at a time.

Only enough code to pass the current test
Don't anticipate future tests
Keep tests focused on observable behavior

对剩下的每一项行为，都执行

RED → GREEN

流程，一次仅处理一个测试。

仅编写足够通过当前测试的代码
不要预判未来的测试需求
保证测试聚焦于可观测的行为

4. Refactor

4. 重构

After all tests pass, look for refactor candidates:

Extract duplication
Deepen modules (move complexity behind simple interfaces)
Apply SOLID principles where natural
Consider what new code reveals about existing code
Run tests after each refactor step

Never refactor while RED. Get to GREEN first.

所有测试都通过后，找出可重构的点：

提取重复代码
深化模块（把复杂逻辑收敛到简单接口背后）
自然适配SOLID原则
思考新代码暴露的现有代码问题
每完成一步重构就运行测试

永远不要在RED阶段重构，先进入GREEN阶段再做重构。

Checklist Per Cycle

每轮循环检查清单

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive an internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive an internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added

tdd

Original

Translation