grimaldost Test-Driven Development
Write the test first and watch it fail. A test you never saw fail proves nothing — it can pass for reasons unrelated to the behavior it was meant to pin.
This is a rigid skill. The bright line: production code is written only against a test you have watched fail. It holds for features, bug fixes, refactors, and behavior changes alike. Exceptions — throwaway prototypes, generated code, pure configuration — are agreed with the user before skipping the cycle, not self-granted.
The cycle
One behavior at a time: red, verify red, green, verify green, refactor.
1. Red — write one failing test
One behavior, a name that describes it, real code over mocks.
// Good: clear name, real behavior, one thing
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);
});
A vague name ("retry works") asserting against a mock tests the mock, not the code.
2. Verify red — watch it fail
Run the test. Confirm three things: it fails rather than errors, the failure
message is the one you expected, and it fails because the feature is missing
— not because of a typo. A test that passes here is testing behavior that
already exists; fix the test. A test that errors is not failing correctly;
fix the error and re-run until it fails for the right reason. One
exception-shaped red IS the right reason: a reproducing test for a crash bug
fails by the very exception under repair — "errors" above means accidental
ones (typos, wrong fixtures), not the crash being reproduced; don't contort
the test to avoid it. (The same red-before-green discipline governs any
verifier, not only tests — verification-before-completion states the
general form for gates and checks.)
3. Green — write the least code that passes
Just enough to pass the test. No speculative parameters, no extra options the
test never asked for, no improvements to neighboring code. Over-engineering
here (a config object with maxRetries, backoff, and onRetry when the
test asked for three retries) is scope the tests don't cover.
4. Verify green — watch it pass
Run again. Confirm: the new test passes, every other test still passes, and the output is pristine — no stray errors or warnings. A failure here means fix the code, not the test.
5. Refactor — clean up on green
Remove duplication, improve names, extract helpers. No new behavior, and the tests stay green throughout. Then write the next failing test.
If code exists before its test
Delete it and start from the test. The time already spent is gone either way; what the rewrite buys is code whose tests have been seen to catch its absence. Keeping the old code "as reference" turns into adapting it, and adapting it is test-after with extra steps — the tests end up describing what the code does instead of what it should do.
Why the order matters
- Tests written after the code pass immediately, and a test that has never failed demonstrates nothing — it may assert the wrong thing, test the implementation rather than the behavior, or miss the cases you forgot.
- Tests-after answer "what does this code do?"; tests-first answer "what should this code do?" The implementation biases what you check — you verify remembered edge cases instead of discovering them.
- Manual testing is ad hoc: no record of what was covered, nothing to re-run when the code changes next month.
Common shortcuts and what they miss
| Shortcut | What it misses |
|---|---|
| "Too simple to test" | Simple code breaks too; the test costs seconds. |
| "I'll add tests after" | Passing immediately proves nothing; see above. |
| "Already manually tested it" | No record, no re-run, edge cases fade. |
| "Keep the old code as reference" | Reference becomes adaptation; adaptation is test-after. |
| "Need to explore the API first" | Explore freely — then discard the spike and start test-first. |
| "This is hard to test" | Hard to test usually means hard to use; simplify the design the test is resisting. |
Good tests
| Quality | Looks like |
|---|---|
| Minimal | One behavior; an "and" in the name means split it |
| Clear | The name states the behavior, not "test1" |
| Intent | Demonstrates the API you wish existed |
When stuck
| Problem | Move |
|---|---|
| Don't know how to test it | Write the wished-for call and the assertion first; ask the user if still stuck |
| Test setup is huge | Extract helpers; if still complex, the design is too coupled |
| Must mock everything | Coupling problem — introduce dependency injection |
| Test too complicated | The interface is too complicated; simplify it |
| A runner that discovers its own tests | Red against a fixture tree, never the real one — test-first a root/target arg, then red the defect through it |
Bug fixes
A bug fix starts with a failing test that reproduces the bug, then follows the same cycle — the test proves the fix and prevents the regression. Diagnosing an unexplained failure belongs to systematic-debugging, which returns here once the cause is proven. Before claiming the fix complete, red-green the regression test (revert the fix, watch it fail, restore) and hand the evidence to verification-before-completion.
Completion check
- Every new behavior has a test that was seen failing for the expected reason
- Minimal code; all tests pass; output pristine
- Mocks only where unavoidable — see testing-anti-patterns.md
- Edge cases and error paths covered
When writing or changing mocks or test utilities, read testing-anti-patterns.md first.