wiki / coding-legacy-characterization-tests / edit

Suggest an edit.

Improvements are reviewed before going live, like any wiki.

Title

One-line summary

The prompt

I need to modify legacy code that has little or no test coverage. Before any change, help me build a characterization safety net — tests that document what the code currently does, not what it should do.

The code:
[PASTE THE LEGACY CODE, INCLUDING ANYTHING IT CALLS THAT YOU CAN SHARE]
The change I eventually need to make: [DESCRIBE THE PLANNED MODIFICATION]
Test framework: [FRAMEWORK]

Work through:

1. Dependency audit: list every external thing this code touches — globals, static state, clock, filesystem, network, database, environment variables, randomness. Classify each: injectable as-is, needs a seam, or tolerable in tests.

2. Seams: for each dependency that needs one, propose the least invasive seam that makes the code testable — a parameter with a default that preserves current behavior, an extracted interface, a thin wrapper — and show the exact edit. Seam edits must be mechanical: no logic changes, no cleanup, however tempting.

3. Characterization tests: write tests that capture current behavior, prioritized by what the planned change could plausibly break. Where the correct output is unknown, assert whatever the code actually produces and mark it with a comment: this pins current behavior, it does not endorse it. Include the ugly cases — exception paths, boundary inputs, order-dependent state — because those are what refactors silently change.

4. Coverage honesty: list the behaviors you could not pin down and why (nondeterminism, unreachable setup, unknown production inputs). For each, say what information or access would close the gap.

5. Green-light criteria: state what must be true before I start the real modification — which tests exist and pass, which seams are in place — so I have a concrete checklist rather than a feeling of readiness.

Throughout, if you find what looks like a bug, record it in a separate "suspected defects" list. Do not fix anything at this stage.

Write it so someone can paste it straight into Claude, ChatGPT or Gemini and fill the [BRACKETS].