Characterisation tests: pinning what legacy code actually does

Goal

Put a safety net around code whose intended behaviour is unknown or undocumented, so that it can be refactored or replaced with confidence that observable behaviour has not changed.

Prerequisites

The code can be called from a test harness, possibly after breaking one dependency through a seam (a parameter, an environment variable, an injected collaborator); inputs can be captured from production or constructed; the code can be run repeatedly without harm.

Steps

1. Choose a unit with a clear boundary (a function, a request handler, a batch job) and list its inputs and observable outputs, including side effects: files written, rows changed, messages sent.
2. Write a test with a placeholder expectation and run it. Feathers describes starting with a test named x and a dummy expected value, reading the actual value from the assertion failure, pasting it into the test, and then renaming the test to describe what the code does.
3. Repeat for inputs that reach other branches: empty, boundary, malformed, large, unusual encodings. Use coverage to find branches no test has reached yet.
4. For large outputs, store the serialised output in a snapshot or approval file with volatile fields (timestamps, ids) redacted, and keep the file under review.
5. Record surprises without fixing them. Feathers' point is that the purpose is to document the system's actual behaviour, not the behaviour one wishes it had; something that looks like a bug may be relied upon. Keep a list of suspected bugs to be decided with the system's owners.
6. Run the suite before and after each refactoring step. Any changed output is either a mistake or a decision; a decision gets a ticket and an updated test whose name says why.
7. Once the intended behaviour is known, tighten tests into specification tests and delete characterisation tests that only pinned incidental output.

Expected result

A suite that fails whenever observable behaviour changes, a list of suspected bugs with owners, and the freedom to restructure the code.

Limits and test basis

Characterisation tests pin incidental behaviour (ordering, formatting), so they fail on harmless changes and must be revisited. They cover only the inputs someone thought of; samples of production data widen that. Breaking dependencies to reach the code is the hard part and may itself require small edits made without protection. No measurement is claimed.