Characterization tests

Legacy code is not old code. Michael Feathers' useful definition: code without tests, or without tests you trust. Untested code resists change because every edit is a bet. A characterization test documents what the code does today, including the weird parts, so you can move structure later without changing output by accident.

You are not asserting the ideal. You are locking reality. Once those tests are green, you may tidy toward maintainable code. Change behavior in a separate commit.

Walking through it

Before you touch a scary invoice module, pin a production case you are not ready to "fix."

// Sketch: pin today's weird but load-bearing rounding.
test("invoice total matches production fixture 2024-11-02", () => {
  const input = readFixture("invoices/legacy-case-77.json")
  expect(legacyInvoiceTotal(input)).toBe(1044) // cents; do not "fix" yet
})

Generate fixtures from production samples and scrub PII. Cover the paths you will touch. Golden-master or snapshot tests work when the output is large and stable enough to review when it changes.

A large pricing engine with no tests is the same move at larger scale: pin production quotes first. Only then extract, flag, and ramp. See incremental migrations for the later weeks.

Common mistakes

• Skipping tests because you are careful. You are not. Characterization is the care.
• Asserting the ideal while characterizing. Freeze today's rounding first. Fix it later.
• Abstracting too early. Do not invent a new design while you are still learning what the old one does.
• Hiding a behavior change inside the first cleanup PR. Reviewers miss it; bisect lies.

Check yourself

1. A characterization test fails after a rename. Did you refactor, or change behavior? If the output changed, you changed behavior. A rename alone should stay green.

2. You notice an off-by-one while writing fixtures. Do you fix it in the same PR? No. Finish the structural work green against the pin, then open a second PR with a failing test for the bug.

Key takeaways

• Legacy means untested, not old.
• Characterization tests pin today's behavior, including scars you are not ready to heal.
• Use production fixtures on the paths you will touch.
• Only after the pins are green should you tidy, then change behavior.

Further learning

Next, create a place to stand with seams.