Topics / Engineering practice
Characterization tests preserve observed behavior. Decide which behavior deserves preservation.
Capture what the existing system does, then separate accepted compatibility from accidental behavior before making it the contract for a replacement.
Capture the observation without granting it authority.
A characterization test records an existing output or effect. That is useful when documentation is missing. It does not tell you whether a surprising result is a customer promise, a tolerated defect or an implementation accident.
Illustrative example
A parser accepts an invalid date.
The old parser normalizes 31 February into another date. A captured-output test preserves that behavior. Before demanding parity, ask whether users depend on it, whether it violates the intended input contract and who can authorize a change.
Make the parity scope explicit.
- Choose representative normal, boundary and failure inputs.
- Record outputs, errors and durable side effects.
- Normalize only differences you have justified, such as nondeterministic timestamps.
- Classify mismatches as intended change, defect or unresolved behavior.
- Keep exclusions and approvals next to the comparison.
The cases establish parity only for the observed conditions. A finite corpus is not a proof of equivalence for all inputs.
Use a mirror record to manage the remaining work.
Proof’s mirror commands track cross-implementation parity contracts and their gaps. The record can organize migration obligations, but completing the ledger does not itself execute every behavior or establish universal equivalence. Review exemptions as part of the decision.
proof mirror list
proof mirror statusStart with one boundary whose behavior you can observe from both implementations. Retain the reason for each intentional difference.
Try it on your software
Bring an old and a replacement implementation.
We can define the behavior to compare and the differences that need a product decision.