Characterize legacy behavior before reshaping the code

When legacy code is poorly understood, first capture what callers can observe: returned values, persisted changes, emitted messages, external calls, timing boundaries that matter, and error behavior. Use those characterization tests as a safety net, then decide explicitly which behaviors are enduring contracts and which are defects to remove.

Find a stable seam

Avoid tests that mirror private methods and object layout. Test through a public function, HTTP endpoint, command, message handler, or database boundary that can survive the refactor. Replace unstable external systems with recording fakes at their interfaces, while keeping enough integration coverage to catch wiring errors.

A contract test focuses on the messages exchanged at a service boundary. Martin Fowler’s contract test description explains how tests can verify that an external service continues to meet the expectations a component relies on. The same principle helps legacy refactoring: capture only observable obligations, not the old internal path.

Start with representative production inputs from logs or support cases after removing sensitive data. Add boundary values, known failures, and one example for each meaningful branch. If output order or formatting varies without semantic meaning, normalize it before comparison rather than freezing noise.

Capture side effects and failures

Return values are often the smallest part of legacy behavior. Record database changes, transaction boundaries, messages, retries, idempotency behavior, files, and calls to dependencies. For an invoice job, verify the ledger entries and event payload, not the sequence of helper calls.

Errors deserve first-class cases. Does the function reject before writing, leave partial work, retry, or translate a dependency error? A refactor that changes partial failure can create duplicate charges even when every success snapshot matches.

Use golden files sparingly for structured, stable outputs. Review them as code. A 5,000-line snapshot that changes on every run is not characterization; it is an approval bypass.

Keep uncertainty visible

Some current behavior is accidental yet depended upon. Label each captured case as confirmed contract, compatibility hold, suspected defect, or unknown. Do not silently encode a suspected defect forever. Create a decision task with owner and evidence, then keep the temporary test until the decision is made.

Production comparison can help. Run old and new implementations in shadow for read-only computations, compare normalized outputs, and investigate differences. Never double-execute side effects. For mutating workflows, replay recorded inputs in an isolated environment or compare a planned effect description.

Refactor in reversible slices

Establish the test, make one structural change, and keep behavior constant. Extract a boundary, introduce a new representation, or route one case to the replacement. Small commits and feature switches narrow the search space when behavior changes.

Git’s bisect documentation shows how binary search identifies the change that introduced a known bad behavior and can automate evaluation with a test script. A reliable characterization test makes that technique useful: it supplies an objective good or bad signal across the history or refactor series.

Avoid broad mocks that return whatever the test expects. They can allow both old and new implementations to be wrong in the same way. Prefer fakes with domain invariants or contract tests against a real dependency in a controlled environment.

Decide which tests remain

After replacement, rewrite confirmed contracts in domain language against the new stable interface. Keep regression tests for harmful failures and important edge behavior. Delete temporary tests that assert obsolete implementation details or deliberately changed quirks. Preserve the evidence and decision record for removed compatibility behavior.

Measure confidence by covered risks, not line percentage: money movement, authorization, retries, duplicate messages, migration formats, and user-visible errors deserve focused examples.

Choose one legacy entry point and record five real scenarios: ordinary success, boundary input, dependency failure, retry, and partial side effect. Classify each behavior before changing code. The first refactor should move one dependency behind a stable seam while every captured observation remains unchanged.