prove-the-test

name	prove-the-test
description	Prove a test fails when the code is wrong before you trust it green. Use when writing or reviewing a test for a change or bug fix, when a change ships with passing tests you are not sure cover it, or when the user asks "does this test have teeth", "is this covered", or "add a test for this fix".

Prove the test

The failure this prevents: a test passes while the code is still wrong. A test is worth keeping only if it goes red when the change is reverted. Everything here serves that.

The proof: revert the change, watch the committed suite go red

Revert the change under test (the fix line, the new behavior). Run the committed suite. Watch a test go red. Restore. A test you have not watched fail against the real revert has no teeth, and a green you did not earn this way is a guess.

These do not count as the proof:

• a new test that passes: green alone says nothing about what would turn it red
• a manual run or an e2e you watched fail by hand: that is an acceptance check, not a committed guard, so CI still has nothing

If reverting the change leaves the whole suite green, the change is uncovered. Move or add a test until the revert turns something red.

Test the code that changed, not the code beside it

Extracting a helper and testing the helper does not test the caller that changed. If the bug lived in how the caller wires the pieces together, a green helper test is false confidence. This is the helper-vs-caller trap: you tested the extraction, not the integration.

Choose the seam (the boundary where the change's behavior is observable) at the level the bug occurs:

• the bug needs two callers: a single-caller test cannot catch it
• the bug is in the wiring: drive the wired path, not the pure function under it
• only a too-shallow seam is reachable: say so. The architecture is blocking the guard, which is a finding, not a test to fake green.

What a test worth keeping is

• checks behavior through a public seam, not internal structure, so it survives a refactor and breaks only when behavior breaks
• takes its expected value from an independent source (a known-good literal, a worked example, the spec), never recomputed the way the code computes it. A test that recomputes the answer passes by construction and can never disagree with the code.
• reads like a claim about what the system does, so a failure names what broke

Red before green

Write the failing test first. Watch it fail for the right reason (a wrong assertion, not a file that will not load). Then write only enough code to pass it. A test written after the code and never seen red is the most common toothless test.