test-driven-development

Test-Driven Development

Write a failing test before writing the code that makes it pass. For bug fixes, reproduce the bug with a test before attempting a fix. A test that passes on its first run proves nothing — it may be testing the wrong thing.

The cycle

1. RED — write a test for behavior that doesn't exist yet. Run it. It must fail. If it passes immediately, the test is wrong, not the code.
2. GREEN — write the minimum code to pass. Don't add behavior the test doesn't require.
3. REFACTOR — clean up with tests green. Re-run tests after every step.

The Prove-It Pattern (bug fixes)

Do not edit the implementation until a reproduction test exists and its failure has been shown. This applies even to a one-line fix that looks obviously correct — the reproduction test is what proves the bug was real and what proves the fix addresses it, not the author's confidence in the diagnosis. Sequence, every time:

1. Write a test that reproduces the reported bug.
2. Run it and show that it fails, with the failure output.
3. Only then change the implementation.
4. Re-run the same test and show it now passes.

// Bug report: "CompleteTask doesn't set CompletedAt"
func TestCompleteTask_SetsCompletedAt(t *testing.T) {
	task := createTask(t, "test")
	completed, err := completeTask(task.ID)
	if err != nil {
		t.Fatalf("completeTask: %v", err)
	}
	if completed.CompletedAt.IsZero() {
		t.Fatal("CompletedAt was not set") // fails first — confirms the bug
	}
}

Go specifics

• Use table-driven tests for multiple input variations — one t.Run subtest per case, named for the behavior, not "case 1".
• Call t.Parallel() inside the subtest closure, and be aware that the common table-driven footgun is capturing the loop variable by reference across a range in Go versions before 1.22; if this repo's go.mod targets Go < 1.22, shadow the loop variable (tt := tt) before calling t.Parallel(), or Go 1.22+'s per-iteration loop variable semantics make it unnecessary.
• Prefer the standard library's testing package and testify/require for fatal assertions; reserve testify/assert for checks that should continue after failure to surface multiple problems in one run.