Characterization tests

A refactoring is, by definition, a behavior-preserving change — so you need a way to detect if behavior moved. The point of refactoring is to improve structure without changing what the code does. The only way to make that guarantee instead of hoping for it is to have something that fails the moment behavior shifts. On code with a real test suite, that something is the suite. On untested legacy, you have nothing — so any “refactor” is actually an unverified rewrite, and the bugs you introduce surface in production, weeks later, far from the edit.

The net has to exist before the change. You cannot add it after you’ve already moved the behavior, because then you’ve baked the drift into the baseline.

A characterization test asserts the code’s actual output, not its correct output. This is the move that breaks the chicken-and-egg. You don’t need to know the right answer to write the test; you need the current answer, and the code will tell you that. Feathers’ technique: call the function, see what it returns, and write that exact value into the assertion — even if it looks wrong.

// You suspect the right answer is ~7.50, but you do not assert that.
// You run the code and assert whatever it actually produced.
test('characterizes shippingCost for a 2kg domestic parcel', () => {
  expect(shippingCost({ weightKg: 2, zone: 'domestic' })).toBe(6.99);
});

Where did 6.99 come from? You wrote .toBe(0), ran it, the failure message said Expected 0, Received 6.99, and you pasted 6.99 back in. The test now passes and pins that input-output pair. You are not claiming 6.99 is correct. You are claiming “this is what the system does today,” and now any refactor that changes it will fail loudly.

Pin the behavior that actually exercises the code, including the ugly branches — coverage of paths matters more than coverage of “happy” cases. A safety net with holes lets behavior fall through. The branches most likely to break under refactoring are the weird ones: the zero-weight edge, the unknown-zone fallback, the rounding quirk, the early return that nobody remembers. Characterize those deliberately. A fast way to find them is to feed varied inputs and snapshot the outputs in bulk — the “golden master” approach — so you pin a wide swath of behavior cheaply rather than hand-writing one assertion at a time.

// Golden master: pin many input/output pairs at once.
const cases = [
  { weightKg: 0,   zone: 'domestic' },
  { weightKg: 2,   zone: 'domestic' },
  { weightKg: 2,   zone: 'intl' },
  { weightKg: 99,  zone: 'unknown' }, // the fallback path
];
test('golden master: shippingCost across known paths', () => {
  const observed = cases.map((c) => ({ ...c, cost: shippingCost(c) }));
  expect(observed).toMatchSnapshot(); // first run records, later runs compare
});

The first run records the snapshot — that recording is the characterization. From then on the suite screams if any path’s output moves. Aim the net where the refactor is most likely to slip, not where the code is obviously simple.

Pinning current behavior pins the bugs too — and that is fine, as long as you keep “pin” and “fix” as two separate, separately-tested decisions. This is the senior failure mode. You characterize the function, the snapshot includes a line that says intl shipping for 0kg returns 4.20 when it obviously should be 0, and now your green suite enforces that bug. If you treat the characterization test as the spec, you will be afraid to ever fix it, because fixing it turns the suite red and “the tests were passing.”

The discipline: a characterization test is a temporary description of reality, not a requirement. Refactor under it — green means “I preserved behavior, including the wrong parts, while improving structure.” Then, as a distinct commit with its own intent, change the buggy behavior: write a new test asserting the correct 0, watch the old characterization line fail, update it on purpose, and note in the commit that this is a deliberate behavior change, not a regression. Refactoring keeps the net green; fixing turns it red on purpose. Conflating the two is how teams end up petrified of their own legacy code.