Back to Details

validation-first-approach

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

红 - 编写失败的测试

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);
});
名称模糊，测试的是模拟而非实际代码 </Bad>
要求：
  • 仅测试一个行为
  • 名称清晰明确
  • 使用真实代码（除非万不得已，否则不要用模拟）

Verify RED - Watch It Fail

验证红状态 - 确认测试失败

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

绿 - 编写最小化代码

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

验证绿状态 - 确认测试通过

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

重构 - 代码清理

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： 空邮箱被接受
红状态
typescript
test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});
验证红状态
bash
$ npm test
FAIL: expected 'Email required', got undefined
绿状态
typescript
function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}
验证绿状态
bash
$ npm test
PASS
重构 如果需要，提取通用的多字段验证逻辑。

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.
在标记工作完成前：
  • 每个新函数/方法都有对应的测试
  • 每个测试在实现前都确认过失败
  • 每个测试的失败原因符合预期（功能缺失，而非拼写错误）
  • 编写的代码刚好满足测试要求
  • 所有测试都通过
  • 输出干净（无错误、无警告）
  • 测试使用真实代码（除非万不得已否则不用模拟）
  • 覆盖了边缘情况和错误场景
如果有任何一项无法勾选？说明你跳过了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，先写断言。咨询团队成员。
测试太复杂设计太复杂了。简化接口。
必须到处用模拟代码耦合度太高。使用依赖注入。
测试准备工作太繁琐提取辅助函数。如果还是复杂？简化设计。

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
添加模拟或测试工具时，请阅读@testing-anti-patterns.md以避免常见陷阱：
  • 测试模拟行为而非真实行为
  • 为生产类添加仅用于测试的方法
  • 在不理解依赖的情况下使用模拟

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
除非得到团队成员的许可，否则没有例外。