Freeze the behavior before moving the machinery

Characterize the seam, not the entire system

A characterization test records what an existing system does at a boundary you intend to preserve while changing its internals. Choose a seam that a caller can observe: a command's exit status and output, an API response, a serialized record, or calls to a stable adapter. Trying to snapshot an entire application creates a baseline too large to understand. The aim is a reviewable tripwire around the refactor's blast radius, not a claim that the legacy behavior is fully specified.

Map inputs to outputs and side effects before editing. Include representative normal, boundary, and failure cases. Label behaviors that are known defects rather than silently blessing them. If a later change intentionally fixes one, change the requirement and test together in a separate, reviewable step.

Use snapshots selectively

Snapshot testing can efficiently record structured output, and Jest documents that later runs compare rendered output with the stored reference. That convenience shifts judgment to review time. Normalize volatile IDs, timestamps, and ordering before capture; otherwise every run produces churn. Keep snapshots small enough that a reviewer can explain each changed line. A hundred-line serialized object may hide one meaningful field among formatting details.

For a hypothetical invoice formatter, a compact snapshot of headings, totals, and line order could protect presentation while direct assertions protect rounding and tax rules. The example is illustrative; no formatter was run here. Snapshot updates should never be accepted solely because an agent says the new output is expected.

Jest snapshot testing ↗

Create a two-column behavior ledger

Before the refactor, record each protected case and its present outcome. Beside it, write the intended status after the change: unchanged, deliberately changed, or not yet understood. This ledger prevents an agent from interpreting every test failure as something to patch around. It also exposes disputed behavior early. If nobody knows whether empty input should return an empty result or an error, that is a product decision, not a refactoring detail.

Run the baseline on the untouched revision and retain exact commands and environment assumptions. When the system depends on external services, capture approved fixtures at the adapter boundary and document what fidelity they lose. A recorded response does not model latency, authentication expiry, or provider evolution.

Move one seam at a time

Make each structural change independently reversible: extract a function, introduce an adapter, redirect one caller, then compare the behavior ledger. Keep deletion of the old path until the new path has been exercised. An agent can help enumerate callers and draft tests, but a maintainer should decide which behavior is contractual and inspect changes to logging, authorization, errors, and resource use that snapshots may miss.

Characterization reduces uncertainty; it does not prove equivalence. Concurrency races, production data distributions, timing, and undocumented integrations may remain outside the harness. State those limits in the handoff, along with the cases compared and any baseline output intentionally changed.

Jest expectations and explicit matchers ↗