tdd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Test-Driven Development (TDD)

Overview

概述

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

先编写测试。看着测试失败。编写最少的代码让测试通过。

**核心原则：**如果你没看到测试失败，你就不知道它是否测试了正确的内容。

违反规则的字面要求就是违反规则的精神。

When to Use

适用场景

Always:

New features
Bug fixes
Refactoring
Behavior changes

Exceptions (ask your human partner):

Throwaway prototypes
Generated code
Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization.

始终适用：

新功能开发
Bug修复
代码重构
行为变更

例外情况（请咨询你的人类搭档）：

一次性原型
生成代码
配置文件

想着“就这一次跳过TDD”？打住。这只是合理化借口。

The Iron Law

铁律

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

Don't keep it as "reference"
Don't "adapt" it while writing tests
Don't look at it
Delete means delete

Implement fresh from tests. Period.

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

先写代码再写测试？删掉它。重新开始。

无例外：

不要把它当作“参考”保留
不要在写测试时“修改”它
不要看它
删除就是彻底删除

根据测试重新实现。就这么简单。

Red-Green-Refactor

Red-Green-Refactor（红-绿-重构）

dot

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

dot

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED - Write Failing Test

RED - 编写失败的测试

Write one minimal test showing what should happen.

<Good> ```typescript test('retries failed operations 3 times', async () => { let attempts = 0; const operation = () => { attempts++; if (attempts < 3) throw new Error('fail'); return 'success'; };

const result = await retryOperation(operation);

expect(result).toBe('success'); expect(attempts).toBe(3); });

Clear name, tests real behavior, one thing
</Good>

<Bad>
```typescript
test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

Vague name, tests mock not code </Bad>

Requirements:

One behavior
Clear name
Real code (no mocks unless unavoidable)

编写一个最小化的测试，展示预期的行为。

<Good> ```typescript test('retries failed operations 3 times', async () => { let attempts = 0; const operation = () => { attempts++; if (attempts < 3) throw new Error('fail'); return 'success'; };

const result = await retryOperation(operation);

expect(result).toBe('success'); expect(attempts).toBe(3); });

名称清晰，测试真实行为，仅测试一件事
</Good>

<Bad>
```typescript
test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

名称模糊，测试的是mock而非代码 </Bad>

要求：

仅测试一种行为
名称清晰
使用真实代码（除非万不得已，否则不使用mock）

Verify RED - Watch It Fail

验证RED - 确认测试失败

MANDATORY. Never skip.

bash

npm test path/to/test.test.ts

Confirm:

Test fails (not errors)
Failure message is expected
Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

必须执行，绝不能跳过。

bash

npm test path/to/test.test.ts

确认：

测试失败（不是报错）
失败信息符合预期
失败原因是功能缺失（而非拼写错误）

**测试通过了？**你在测试已有的行为。修改测试。

**测试报错了？**修复错误，重新运行直到测试正确失败。

GREEN - Minimal Code

GREEN - 编写最少代码

Write simplest code to pass the test.

<Good> ```typescript async function retryOperation<T>(fn: () => Promise<T>): Promise<T> { for (let i = 0; i < 3; i++) { try { return await fn(); } catch (e) { if (i === 2) throw e; } } throw new Error('unreachable'); } ``` Just enough to pass </Good> <Bad> ```typescript async function retryOperation<T>( fn: () => Promise<T>, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise<T> { // YAGNI } ``` Over-engineered </Bad>

Don't add features, refactor other code, or "improve" beyond the test.

编写最简单的代码让测试通过。

<Good> ```typescript async function retryOperation<T>(fn: () => Promise<T>): Promise<T> { for (let i = 0; i < 3; i++) { try { return await fn(); } catch (e) { if (i === 2) throw e; } } throw new Error('unreachable'); } ``` 刚好满足测试要求 </Good> <Bad> ```typescript async function retryOperation<T>( fn: () => Promise<T>, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise<T> { // YAGNI（You Ain't Gonna Need It，你不会用到它） } ``` 过度设计 </Bad>

不要添加额外功能、重构其他代码或做超出测试要求的“优化”。

Verify GREEN - Watch It Pass

验证GREEN - 确认测试通过

MANDATORY.

bash

npm test path/to/test.test.ts

Confirm:

Test passes
Other tests still pass
Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

必须执行。

bash

npm test path/to/test.test.ts

确认：

测试通过
其他测试仍然通过
输出干净（无错误、警告）

**测试失败？**修复代码，而非测试。

**其他测试失败？**立即修复。

REFACTOR - Clean Up

REFACTOR - 代码清理

After green only:

Remove duplication
Improve names
Extract helpers

Keep tests green. Don't add behavior.

仅在测试通过后进行：

消除重复代码
优化命名
提取辅助函数

保持测试通过。不要添加新行为。

Repeat

重复循环

Next failing test for next feature.

为下一个功能编写新的失败测试。

Good Tests

优质测试

Quality	Good	Bad
Minimal	One thing. "and" in name? Split it.	`test('validates email and domain and whitespace')`
Clear	Name describes behavior	`test('test1')`
Shows intent	Demonstrates desired API	Obscures what code should do

质量	优质示例	糟糕示例
最小化	只测试一件事。名称里有“和”？拆分它。	`test('validates email and domain and whitespace')`
清晰性	名称描述行为	`test('test1')`
体现意图	展示期望的API	模糊代码应有的功能

Why Order Matters

顺序的重要性

"I'll write tests after to verify it works"

Tests written after code pass immediately. Passing immediately proves nothing:

Might test wrong thing
Might test implementation, not behavior
Might miss edge cases you forgot
You never saw it catch the bug

Test-first forces you to see the test fail, proving it actually tests something.

"I already manually tested all the edge cases"

Manual testing is ad-hoc. You think you tested everything but:

No record of what you tested
Can't re-run when code changes
Easy to forget cases under pressure
"It worked when I tried it" ≠ comprehensive

Automated tests are systematic. They run the same way every time.

"Deleting X hours of work is wasteful"

Sunk cost fallacy. The time is already gone. Your choice now:

Delete and rewrite with TDD (X more hours, high confidence)
Keep it and add tests after (30 min, low confidence, likely bugs)

The "waste" is keeping code you can't trust. Working code without real tests is technical debt.

"TDD is dogmatic, being pragmatic means adapting"

TDD IS pragmatic:

Finds bugs before commit (faster than debugging after)
Prevents regressions (tests catch breaks immediately)
Documents behavior (tests show how to use code)
Enables refactoring (change freely, tests catch breaks)

"Pragmatic" shortcuts = debugging in production = slower.

"Tests after achieve the same goals - it's spirit not ritual"

No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"

Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.

Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).

30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.

“我会之后写测试来验证它能运行”

在代码之后写的测试会立即通过。立即通过的测试证明不了任何事情：

可能测试了错误的内容
可能测试的是实现细节而非行为
可能遗漏了你忘记的边缘情况
你从未看到它捕获过bug

先写测试会迫使你看到测试失败，证明它确实测试了某些内容。

“我已经手动测试了所有边缘情况”

手动测试是临时的。你以为测试了所有内容，但：

没有测试记录
代码变更后无法重新运行测试
压力下容易忘记测试场景
“我试的时候是好的”≠全面测试

自动化测试是系统化的。每次运行的方式都一致。

“删掉X小时的工作太浪费了”

沉没成本谬误。时间已经花了。你现在的选择是：

删除并重新用TDD编写（再多花X小时，高可信度）
保留它并事后加测试（30分钟，低可信度，可能有bug）

“浪费”的是保留你无法信任的代码。没有真实测试的可用代码是技术债务。

“TDD太教条了，务实意味着灵活变通”

TDD才是务实的：

在提交前发现bug（比事后调试更快）
防止回归（测试立即捕获代码破坏）
记录行为（测试展示如何使用代码）
支持重构（自由修改，测试捕获破坏）

“务实”的捷径=生产环境调试=更慢。

“事后测试能达到同样的目标——重要的是精神而非形式”

不对。事后测试回答的是“这代码做了什么？” 先写测试回答的是“这代码应该做什么？”

事后测试会受你的实现方式影响。你测试的是你构建的内容，而非需求内容。你验证的是你记得的边缘情况，而非发现的边缘情况。

先写测试会迫使你在实现前发现边缘情况。事后测试只能验证你是否记得所有情况（你肯定没全记住）。

30分钟的事后测试≠TDD。你得到了覆盖率，但失去了测试有效的证明。

Common Rationalizations

常见合理化借口

Excuse	Reality
"Too simple to test"	Simple code breaks. Test takes 30 seconds.
"I'll test after"	Tests passing immediately prove nothing.
"Tests after achieve same goals"	Tests-after = "what does this do?" Tests-first = "what should this do?"
"Already manually tested"	Ad-hoc ≠ systematic. No record, can't re-run.
"Deleting X hours is wasteful"	Sunk cost fallacy. Keeping unverified code is technical debt.
"Keep as reference, write tests first"	You'll adapt it. That's testing after. Delete means delete.
"Need to explore first"	Fine. Throw away exploration, start with TDD.
"Test hard = design unclear"	Listen to test. Hard to test = hard to use.
"TDD will slow me down"	TDD faster than debugging. Pragmatic = test-first.
"Manual test faster"	Manual doesn't prove edge cases. You'll re-test every change.
"Existing code has no tests"	You're improving it. Add tests for existing code.

借口	现实
“太简单了不需要测试”	简单代码也会出错。写测试只需要30秒。
“我之后再测试”	立即通过的测试证明不了任何事情。
“之后写测试能达到同样的目标”	事后测试=“这代码做了什么？” 先写测试=“这代码应该做什么？”
“已经手动测试过了”	临时测试≠系统化测试。没有记录，无法重新运行。
“删掉X小时的工作太浪费了”	沉没成本谬误。保留未验证的代码是技术债务。
“保留作为参考，先写测试”	你会忍不住修改它。这本质还是事后测试。删除就是彻底删除。
“需要先探索一下”	没问题。丢掉探索代码，用TDD重新开始。
“测试难度大=设计不清晰”	倾听测试的反馈。难测试=难使用。
“TDD会拖慢我的速度”	TDD比调试更快。务实=先写测试。
“手动测试更快”	手动测试无法证明边缘情况。你每次变更都要重新测试。
“现有代码没有测试”	你正在改进它。为现有代码添加测试。

Red Flags - STOP and Start Over

危险信号 - 停止并重新开始

Code before test
Test after implementation
Test passes immediately
Can't explain why test failed
Tests added "later"
Rationalizing "just this once"
"I already manually tested it"
"Tests after achieve the same purpose"
"It's about spirit not ritual"
"Keep as reference" or "adapt existing code"
"Already spent X hours, deleting is wasteful"
"TDD is dogmatic, I'm being pragmatic"
"This is different because..."

All of these mean: Delete code. Start over with TDD.

在测试之前写代码
在实现之后写测试
测试立即通过
无法解释测试失败的原因
“稍后”添加测试
合理化“就这一次”
“我已经手动测试过了”
“事后测试能达到同样的目的”
“重要的是精神而非形式”
“保留作为参考”或“修改现有代码”
“已经花了X小时，删掉太浪费了”
“TDD太教条了，我是务实的”
“这次情况不一样因为...”

所有这些都意味着：删除代码。用TDD重新开始。

Example: Bug Fix

示例：Bug修复

Bug: Empty email accepted

RED

typescript

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Verify RED

bash

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

typescript

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Verify GREEN

bash

$ npm test
PASS

REFACTOR Extract validation for multiple fields if needed.

**Bug：**空邮箱被接受

RED

typescript

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

验证RED

bash

$ npm test
FAIL: expected 'Email required', got undefined

GREEN

typescript

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

验证GREEN

bash

$ npm test
PASS

REFACTOR 如果需要，提取多字段的验证逻辑。

Verification Checklist

验证清单

When Stuck

遇到困境时

Problem	Solution
Don't know how to test	Write wished-for API. Write assertion first. Ask your human partner.
Test too complicated	Design too complicated. Simplify interface.
Must mock everything	Code too coupled. Use dependency injection.
Test setup huge	Extract helpers. Still complex? Simplify design.

问题	解决方案
不知道如何测试	写出期望的API。先写断言。向你的人类搭档求助。
测试太复杂	设计太复杂。简化接口。
必须mock所有东西	代码耦合度太高。使用依赖注入。
测试设置工作量大	提取辅助函数。仍然复杂？简化设计。

Debugging Integration

调试集成

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.

Never fix bugs without a test.

发现bug？编写能重现它的失败测试。遵循TDD循环。测试证明修复有效并防止回归。

永远不要在没有测试的情况下修复bug。

Testing Anti-Patterns

测试反模式

When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:

Testing mock behavior instead of real behavior
Adding test-only methods to production classes
Mocking without understanding dependencies

添加mock或测试工具时，请阅读@testing-anti-patterns.md以避免常见陷阱：

测试mock行为而非真实行为
向生产类添加仅用于测试的方法
在不理解依赖的情况下使用mock

Final Rule

最终规则

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without your human partner's permission.

Production code → test exists and failed first
Otherwise → not TDD

未经你的人类搭档许可，无例外。