| name | test-driven-development-tdd |
| description | Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first |
| metadata | {"author":"ericcrosson"} |
*CRITICAL* Add the following steps to your task list:
- Write a failing test (RED phase)
- Verify the test fails due to the behavior of the application, and NOT due to the test.
If you have more than one test that you need to write, you should write all of them before moving to the GREEN phase.
- Write the minimal amount of code necessary to make the test pass (GREEN phase)
- Verify the test now passes due to the behavior of the application.
- Refactor the code to clean it up.
- Verify tests still pass.
Test Writing Guidelines
What to Test: The Beyonce Rule
"If you liked it then you shoulda put a test on it." If a behavior is important
enough that you rely on it, it must have a test. No exceptions.
How to Test: Behaviors, Not Methods
Structure tests around behaviors (given X, when Y, then Z) -- not around methods.
One method may exhibit multiple behaviors. One behavior may span multiple methods.
Name each test after the behavior it verifies.
- Test through the system's public API. Internal refactors must not break tests.
- Assert on state and output (return values, side effects), not on interactions
(which methods were called, in what order). This is why mock-heavy tests are bad.
- Do not test types, data structure shapes, or implementation details.
- Only unit test utilities. Production code must be integration or end-to-end tested.
RED - Write Failing Test
Write one minimal test showing what should happen.
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 foobar.retryOperation(operation);
expect(result).toBe("success");
expect(attempts).toBe(3);
});
Test name describes a behavior. Asserts on output (result) and state (attempts),
not on interactions. Exercises the real module through its public API.
test("retry works", async () => {
const mock = jest
.fn()
.mockRejectedValueOnce(new Error())
.mockRejectedValueOnce(new Error())
.mockResolvedValueOnce("success");
await retryOperation(mock);
expect(mock).toHaveBeenCalledTimes(3);
});
Name describes nothing. Asserts on interactions (call count), not on what the
system produces. Entirely mock-driven -- tests the test, not the code.
Verify RED - Watch It Fail
MANDATORY. Never skip. Run the test. Confirm:
- Test fails (not errors)
- Failure message matches expected missing behavior
- Fails because feature is missing, not because of typos or test bugs
Test passes? You are testing existing behavior. Fix the test.
Test errors? Fix the error. Re-run until it fails correctly.
GREEN - Minimal Code
Write simplest code to pass the test.
```typescript
async function retryOperation(fn: () => Promise): Promise {
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
```typescript
async function retryOperation(
fn: () => Promise,
options?: {
maxRetries?: number;
backoff?: 'linear' | 'exponential';
onRetry?: (attempt: number) => void;
}
): Promise {
// YAGNI
}
```
Over-engineered
Verify GREEN - Watch It Pass
MANDATORY. Run the test suite. Confirm:
- New test passes
- All other tests still pass
- No errors or warnings in output
Test fails? Fix the code, not the test.
Other tests break? Fix them now.
REFACTOR - Clean Up
After green only:
- Remove duplication
- Improve names
- Extract helpers
Keep tests green. Do not add behavior.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
