Testing changes

principal-engineering

writing-unit-tests

Overview

What a change owes

1. Tests change with behavior, in the same change. An empty test diff on a behavior change is a review finding, not a style preference. A pure refactor owes the opposite proof: the existing tests still pass unmodified, which is what makes it a refactor.
2. A bug fix ships its regression test. Named after the failure mode (not the ticket), demonstrated red against the unfixed code and green against the fix; both halves shown, because a regression test that never went red proves only that it compiles. This is what makes the same bug impossible to reintroduce silently.
3. Scenarios are concrete and include the surfaced edges. The edge cases that grounding and review turned up go into tests by name; the happy path alone tests the demo, not the change. When the change's risk is in the failure path, the failure path gets the tests (see

   handling-failures

   : the typed failure surfacing IS behavior).
4. Every task carries its targeted verify command. The specific test invocation that proves this change, runnable alone, stated where the reviewer can run it. "The suite passed" vouches for nothing the suite never covered.
5. Assertions must discriminate. A test that passes regardless of the change proves nothing: break the code once, watch red, unbreak. Non-discriminating assertions are how suites stay green over broken behavior.
6. Aggregates that must reconcile get invariant tests. Anything on the project's declared critical paths (see the risk tiers in

   principal-engineering

   ) that sums, derives, or mirrors other data gets a test asserting the reconciliation itself (the conservation pattern: the aggregate equals what the raw records imply), not just point examples.

The red-test rule

verifying-before-done

What a change does not owe

• Tests for unreachable edges (see

  scoping-changes

  : fencing what cannot happen is dead code with good intentions).
• Tests of framework internals or generated code; test your use of them at the boundary you own.
• A test-first process: whether tests come first is workflow (the TDD skill where installed governs that); this skill governs what must exist when the change ships, whichever order produced it.

Common mistakes

• "Too small to test." Small changes break behavior at the same rate per line; the test takes minutes, the silent regression takes an audit.
• Testing the fix without reproducing the bug. Red-before-green is the half that proves the test sees the defect.
• Counting coverage by feel. Count the changed behaviors against the tests naming them (see the counted-coverage rule in the technical-writer plugin's truth doctrine, same principle).
• Adding the test that discriminates against nothing, ever: an assertion no plausible defect could fail. Distinct from the legitimate pinning test that deliberately passes against both old and new code to guard unchanged adjacent behavior from overcorrection; a pinning test says that is what it is for.