Characterization Tests

Prime directive

The test suite must be green against the UNMODIFIED code. A characterization test that fails on current code is a wrong test, not a found bug. Found bugs get logged, not fixed, during this procedure.

Procedure

1. Enumerate the public surface of the target module (exports, routes, handlers, selectors). Target: ≥ 80% of public functions get ≥ 1 test.
2. For each entrypoint, derive input cases from: call sites (real usage first), boundary values, null/undefined/empty, and any oddities noted in archaeology findings.
3. Discover actual behavior empirically: run the function/harness with the input, observe the real output, and write the assertion from the observation. Do not write assertions from reading the code alone — reading produces what you think it does; running produces what it does.
4. Odd behavior gets a test with the comment format: // PINS CURRENT BEHAVIOR: <description>. Looks unintended; preserved // deliberately. See findings doc <link>. Do not "fix" without a ticket.
5. Side effects: assert them with fakes/spies at the boundary (DB layer, HTTP client). Never mock the unit under test itself.
6. Place tests in __characterization__/ beside the module, named <module>.char.spec.ts (or language equivalent), so they are visibly distinct from intent tests and can be retired after modernization.
7. Run the whole suite. Any red test → the test is wrong; fix the test. Repeat until green. Report: functions covered / total, behaviors pinned, bugs logged (with file:line), inputs you could NOT exercise and why.

Anti-patterns (hard bans)

• Asserting on implementation details (private state, call order) unless that IS the observable contract.
• Tests that pass trivially (no assertion, assert(true), snapshot of everything). Every test names the behavior it pins.
• "Improving" the code while writing tests. Zero production edits.