PromptSharp › Prompt Library › Dev & Engineering › Legacy-code characterization tests: pin what the module DOES before you dare touch it

Legacy-code characterization tests: pin what the module DOES before you dare touch it

You have to change an untested legacy module and you don't fully trust what it does. Wrap it in behavior-pinning tests that document the CURRENT behavior first, so your refactor can't silently change it.

The prompt — copy and run it

You are a senior engineer writing characterization tests (a.k.a. pinning / golden-master tests, after Michael Feathers) for an untested legacy module I am about to change. The goal is a safety net that documents what the code ACTUALLY DOES today — not what it should do — so I can refactor without silently altering behavior. I will paste the module and the context.

Produce:

A) OBSERVED-BEHAVIOR MAP — from the pasted code, the module's public entry points and, for each, the inputs it consumes and the outputs/side effects it produces (return value, mutated state, I/O, exceptions thrown). Mark each output either "determined from code" or "MUST CAPTURE BY RUNNING" where the value cannot be read off the source (formatting, ordering, floating-point, downstream calls).

B) SEAM MAP — the seams where I can sense or separate behavior WITHOUT changing it (object seams via injected collaborators, a wrapping function, a parameterized clock/random/IO). For each: the smallest dependency-breaking edit that makes the code testable while leaving runtime behavior identical, and the risk that edit carries.

C) CHARACTERIZATION SUITE — tests that PIN the current behavior, ordered change-point-first then working outward. For each test: the exact input, the assertion against the OBSERVED output, and a comment `# pins current behavior — captured from a real run, do NOT 'correct' this value`. Include boundary and error paths the module currently exhibits (including current exceptions).

D) GOLDEN MASTER — for any output too large or complex to assert inline (rendered strings, big structures, serialized blobs): a capture-and-diff harness — how to sample a representative range of inputs, snapshot outputs to a golden file on a known-good commit, and fail the test on any diff. Name the exact inputs to sample.

E) CHANGE-SAFETY GATE — the order of operations: pin the change point, run the suite GREEN against the unmodified module, then refactor in small steps keeping it green — plus the one test that most protects the specific change I described.

Inputs: [PASTE THE MODULE + ITS DIRECT DEPENDENCIES] · [WHAT I NEED TO CHANGE + WHY] · [LANGUAGE / TEST FRAMEWORK] · [HOW TO RUN IT / SAMPLE INPUTS I CAN FEED IT]

Rules: Do not invent behavior the code does not demonstrably produce — every asserted value must come from the pasted source or from a real run I perform, and wherever you cannot determine an output, emit a `# CAPTURE:` TODO telling me to run the code and paste the result, never a guessed value. These tests document what IS, not what SHOULD be: if you suspect a bug, PIN the current (even wrong) behavior in the test AND list it separately as a "suspected defect to fix AFTER the net is green" — do not quietly assert the corrected value. Verify every pinned value against an actual execution before relying on the suite; a characterization test asserting an imagined output is worse than none. Keep proprietary or confidential source out of consumer AI tools beyond what I pasted, and strip any secrets, credentials, or real user data from fixtures and golden files.

Why this prompt works

The one rule that makes characterization tests work is the one everyone breaks: the tests must encode the behavior that EXISTS, bugs and all, not the behavior you wish existed — because their only job is to catch your refactor changing something. Forcing every assertion to trace to an observed run (with a CAPTURE TODO instead of a guess) kills the fabricated-output failure that turns a safety net into a lie, and pinning the change point first with a golden master for the messy outputs is exactly Feathers' order for getting untested legacy code under test cheaply.

Frequently asked

Related Dev & Engineering prompts