write-tests-planning

Backend Test Planning

Thesis: Derive test plans from predicates and discriminators before writing code — don't invent coverage after the fact.

Discriminator-Column Test Matrix

When a column branches behavior at runtime, every write path that touches the table needs a test for each value of the discriminator, not just the value the implementer happened to remember.

Common discriminators in this codebase: status, user_type, role, category, type.

The rule:

If column X changes which branch executes, then for every function F that writes to the table, there must be a test for each value of X that F can encounter.

Worked example. A table with status ∈ {open, closed} and two write paths that branch on status needs four cells covered when both paths touch both statuses — not two happy-path tests for the value the implementer remembered first.

When to apply:

• Any column with a CHECK constraint that varies behavior
• Any column the service switches on (status controls which transitions are legal)
• Any column the handler reads to pick a code path (tier controls feature access)

When NOT to apply:

• Columns that only affect display (no behavior fork)
• Columns with one-way transitions where prior states are tested by inheritance (e.g., pending → active → archived — testing archived implicitly exercised active)

Catch this in code review: when a PR adds or modifies a discriminator column, scan every service method that writes to the table. If a branch isn't covered by a test, the PR isn't done.

Test Plan from Predicate

When you write a predicate with multiple terms, the test plan derives mechanically from it. Don't invent the plan — read it off the code.

Predicate shape	Required tests
WHERE x IN ('a', 'b', 'c')	One test per value.
WHERE x = 'a' AND status = 'active'	x match + active, x match + inactive, x miss.
if a || b || c { ... }	One test per disjunct hitting the branch.
switch v { case A: ... case B: ... default: ... }	One per case + default.
errors.As(err, &x) && x.Code == "23505"	Bare 23505, wrapped 23505 (fmt.Errorf("...: %w", ...)), other pg code, non-pg error.