Back to Details

testing-tdd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Test-Driven Development (TDD)

测试驱动开发（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

红-绿-重构循环

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（你不会需要它） } ``` 过度设计 </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

优质测试的标准

QualityGoodBad
MinimalOne thing. "and" in name? Split it.
test('validates email and domain and whitespace')
ClearName describes behavior
test('test1')
Shows intentDemonstrates desired APIObscures 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

常见的自我合理化借口

ExcuseReality
"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

验证 checklist

Before marking work complete:
  • Every new function/method has a test
  • Watched each test fail before implementing
  • Each test failed for expected reason (feature missing, not typo)
  • Wrote minimal code to pass each test
  • All tests pass
  • Output pristine (no errors, warnings)
  • Tests use real code (mocks only if unavoidable)
  • Edge cases and errors covered
Can't check all boxes? You skipped TDD. Start over.
在标记工作完成前：
  • 每个新函数/方法都有对应的测试
  • 在实现前看到每个测试失败
  • 每个测试的失败原因符合预期（功能缺失，而非拼写错误）
  • 编写最少的代码让每个测试通过
  • 所有测试都通过
  • 输出干净（无错误、警告）
  • 测试使用真实代码（除非万不得已，否则不要用Mock）
  • 覆盖了边缘情况和错误场景
无法勾选所有选项？说明你跳过了TDD，重新开始。

When Stuck

遇到瓶颈时的解决方法

ProblemSolution
Don't know how to testWrite wished-for API. Write assertion first. Ask your human partner.
Test too complicatedDesign too complicated. Simplify interface.
Must mock everythingCode too coupled. Use dependency injection.
Test setup hugeExtract helpers. Still complex? Simplify design.
问题解决方案
不知道如何编写测试写出你期望的API，先写断言，咨询团队成员。
测试过于复杂设计过于复杂，简化接口。
必须大量使用Mock代码耦合度过高，使用依赖注入。
测试准备工作繁重提取辅助函数。如果仍然复杂，简化设计。

Debugging Integration

调试与TDD的结合

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
Never fix bugs without a test.
发现Bug？先编写能复现Bug的失败测试，然后遵循TDD流程。测试既能证明Bug已修复，又能防止回归。
永远不要在没有测试的情况下修复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
除非获得团队成员的许可，否则无例外。