Pin It Down: Tests for Code You Didn't Write
Before changing old code that has no tests, write tests that record what it does today, right or wrong, so any change that alters its behavior shows up at once; these characterization tests pin the code down, surprises included, and the surprises become questions for the people who know the business.
Journeyman · Software Development · OOP · Updated
After this lesson you can
- Write characterization tests that record what old code does today, including the surprises
- Explain why a characterization test pins today's behavior, right or wrong, before a change
Key takeaways
- Old code with no tests can't be changed safely: nobody can tell whether a change broke something, because nobody wrote down what it did.
- A characterization test records what the code does today, right or wrong, by running it and keeping its answer as the expected value.
- Pin the edges as well as the middle: zero, the boundaries, big numbers and odd input, which is where the surprises hide.
- When a pin records something that looks wrong, ask before you fix it. The fix is its own change, with its own test.
Before this: The Smell Map, and Exercise: Green Before, Green After from Module 1, which ran its tests after every step.
Every exercise in this course came with tests. Summit Gym's billing code doesn't. It's a year old, the person who wrote it has left, and the owner wants a change in it next week. Code like this, which works, matters, and has no tests and no one who remembers why, is called legacy code. Most working developers spend more of their time in it than in new code.
You can't change it safely yet, because "safely" means "without changing anything else it does", and nobody wrote down what it does. This lesson writes that down, in tests.

The symptom: nobody knows what it does
Here is the function that works out a member's monthly bill. The comment above it in the real code says "basic is $30 plus $12 a class after the fourth". That's not quite everything it does. The only way to find out is to run it:
foreach ((string plan, int classes) in new[] { ("basic", 2), ("basic", 6), ("basic", 9), ("unlimited", 9), ("Basic", 6) })
{
Console.WriteLine( quot;{plan}, {classes} classes: ${MonthlyBill(plan, classes)}");
}
// Basic is $30 plus $12 a class after the fourth.
int MonthlyBill(string plan, int classes)
{
if (plan == "unlimited") { return 60; }
if (plan == "basic")
{
int bill = 30 + Math.Max(0, classes - 4) * 12;
if (bill > 60) { bill = 60; }
return bill;
}
return 0;
}
basic, 2 classes: $30
basic, 6 classes: $54
basic, 9 classes: $60
unlimited, 9 classes: $60
Basic, 6 classes: $0
// Basic is $30 plus $12 a class after the fourth.
int monthlyBill(String plan, int classes) {
if (plan.equals("unlimited")) { return 60; }
if (plan.equals("basic")) {
int bill = 30 + Math.max(0, classes - 4) * 12;
if (bill > 60) { bill = 60; }
return bill;
}
return 0;
}
void main() {
String[] plans = { "basic", "basic", "basic", "unlimited", "Basic" };
int[] classes = { 2, 6, 9, 9, 6 };
for (int i = 0; i < plans.length; i++) {
IO.println(plans[i] + ", " + classes[i] + " classes: quot; + monthlyBill(plans[i], classes[i]));
}
}
basic, 2 classes: $30
basic, 6 classes: $54
basic, 9 classes: $60
unlimited, 9 classes: $60
Basic, 6 classes: $0
def monthly_bill(plan, classes):
"""Basic is $30 plus $12 a class after the fourth."""
if plan == "unlimited":
return 60
if plan == "basic":
bill = 30 + max(0, classes - 4) * 12
if bill > 60:
bill = 60
return bill
return 0
for plan, classes in [("basic", 2), ("basic", 6), ("basic", 9), ("unlimited", 9), ("Basic", 6)]:
print(f"{plan}, {classes} classes: ${monthly_bill(plan, classes)}")
basic, 2 classes: $30
basic, 6 classes: $54
basic, 9 classes: $60
unlimited, 9 classes: $60
Basic, 6 classes: $0
// Basic is $30 plus $12 a class after the fourth.
function monthlyBill(plan, classes) {
if (plan === "unlimited") { return 60; }
if (plan === "basic") {
let bill = 30 + Math.max(0, classes - 4) * 12;
if (bill > 60) { bill = 60; }
return bill;
}
return 0;
}
for (const [plan, classes] of [["basic", 2], ["basic", 6], ["basic", 9], ["unlimited", 9], ["Basic", 6]]) {
console.log(`${plan}, ${classes} classes: ${monthlyBill(plan, classes)}`);
}
basic, 2 classes: $30
basic, 6 classes: $54
basic, 9 classes: $60
unlimited, 9 classes: $60
Basic, 6 classes: $0
// Basic is $30 plus $12 a class after the fourth.
function monthlyBill(plan: string, classes: number): number {
if (plan === "unlimited") { return 60; }
if (plan === "basic") {
let bill = 30 + Math.max(0, classes - 4) * 12;
if (bill > 60) { bill = 60; }
return bill;
}
return 0;
}
const cases: [string, number][] = [["basic", 2], ["basic", 6], ["basic", 9], ["unlimited", 9], ["Basic", 6]];
for (const [plan, classes] of cases) {
console.log(`${plan}, ${classes} classes: ${monthlyBill(plan, classes)}`);
}
basic, 2 classes: $30
basic, 6 classes: $54
basic, 9 classes: $60
unlimited, 9 classes: $60
Basic, 6 classes: $0
Two surprises, and the comment mentions neither:
- Basic is capped at $60. Nine classes should be $30 + 5 × $12 = $90, but the bill stops at $60. Is that a rule ("nobody pays more than unlimited") or an accident?
"Basic"with a capital B is billed $0. That looks like a bug. But members may have been signed up that way for a year, and someone may be relying on it.
If you'd started changing the code from the comment, you could have "fixed" the cap without knowing it was there, and some members' bills would have jumped by $30.
There's a third puzzle, outside this function: when a basic member books a fifth class, the booking screen from the last chapter shows that class's drop-in price ($15 for yoga), while the bill adds $12. Two parts of one old system disagree, and nobody remembers which is meant. That's normal in legacy code, and it's a question for the owner, not for you to settle while changing something else.
What would you try?
Read the code carefully and remember it. You'll remember the cap. The next developer won't, and you won't in six months.
Write tests for what the code should do. That's how new code is tested, and here it fails at once: the comment, the code and the owner disagree about what "should" means. You'd be writing your guesses down as facts.
Fix the two surprises first, then write tests. Now you've changed the code before you had any way to tell what you changed.
The fix: pin it down first
The way out is to stop asking what the code should do, and write down what it does: run it, and keep each answer as the expected value of a test. A test like this is called a characterization test: it describes the code's character, quirks included, the way a butterfly is pinned down exactly as it was found before anyone studies it. It isn't saying the answer is right. It's saying the answer hasn't changed.
Here are the five answers above, pinned. They were written against the old function, where all five pass. Now a teammate tries a "tidier" version, written from the comment:
Pin("basic, 2 classes", TidyBill("basic", 2), 30);
Pin("basic, 6 classes", TidyBill("basic", 6), 54);
Pin("basic, 9 classes", TidyBill("basic", 9), 60);
Pin("unlimited, 9 classes", TidyBill("unlimited", 9), 60);
Pin("Basic, 6 classes", TidyBill("Basic", 6), 0);
// A teammate's tidier version, written from the comment.
int TidyBill(string plan, int classes) => plan switch
{
"unlimited" => 60,
"basic" => 30 + Math.Max(0, classes - 4) * 12,
_ => 0,
};
void Pin(string label, int actual, int expected)
{
Console.WriteLine(actual == expected
? quot;pinned: {label}: ${actual}"
: quot;CHANGED: {label}: was ${expected}, now ${actual}");
}
pinned: basic, 2 classes: $30
pinned: basic, 6 classes: $54
CHANGED: basic, 9 classes: was $60, now $90
pinned: unlimited, 9 classes: $60
pinned: Basic, 6 classes: $0
// A teammate's tidier version, written from the comment.
int tidyBill(String plan, int classes) {
return switch (plan) {
case "unlimited" -> 60;
case "basic" -> 30 + Math.max(0, classes - 4) * 12;
default -> 0;
};
}
void pin(String label, int actual, int expected) {
IO.println(actual == expected
? "pinned: " + label + ": quot; + actual
: "CHANGED: " + label + ": was quot; + expected + ", now quot; + actual);
}
void main() {
pin("basic, 2 classes", tidyBill("basic", 2), 30);
pin("basic, 6 classes", tidyBill("basic", 6), 54);
pin("basic, 9 classes", tidyBill("basic", 9), 60);
pin("unlimited, 9 classes", tidyBill("unlimited", 9), 60);
pin("Basic, 6 classes", tidyBill("Basic", 6), 0);
}
pinned: basic, 2 classes: $30
pinned: basic, 6 classes: $54
CHANGED: basic, 9 classes: was $60, now $90
pinned: unlimited, 9 classes: $60
pinned: Basic, 6 classes: $0
def tidy_bill(plan, classes):
"""A teammate's tidier version, written from the comment."""
match plan:
case "unlimited":
return 60
case "basic":
return 30 + max(0, classes - 4) * 12
return 0
def pin(label, actual, expected):
if actual == expected:
print(f"pinned: {label}: ${actual}")
else:
print(f"CHANGED: {label}: was ${expected}, now ${actual}")
pin("basic, 2 classes", tidy_bill("basic", 2), 30)
pin("basic, 6 classes", tidy_bill("basic", 6), 54)
pin("basic, 9 classes", tidy_bill("basic", 9), 60)
pin("unlimited, 9 classes", tidy_bill("unlimited", 9), 60)
pin("Basic, 6 classes", tidy_bill("Basic", 6), 0)
pinned: basic, 2 classes: $30
pinned: basic, 6 classes: $54
CHANGED: basic, 9 classes: was $60, now $90
pinned: unlimited, 9 classes: $60
pinned: Basic, 6 classes: $0
// A teammate's tidier version, written from the comment.
function tidyBill(plan, classes) {
switch (plan) {
case "unlimited": return 60;
case "basic": return 30 + Math.max(0, classes - 4) * 12;
default: return 0;
}
}
function pin(label, actual, expected) {
console.log(actual === expected
? `pinned: ${label}: ${actual}`
: `CHANGED: ${label}: was ${expected}, now ${actual}`);
}
pin("basic, 2 classes", tidyBill("basic", 2), 30);
pin("basic, 6 classes", tidyBill("basic", 6), 54);
pin("basic, 9 classes", tidyBill("basic", 9), 60);
pin("unlimited, 9 classes", tidyBill("unlimited", 9), 60);
pin("Basic, 6 classes", tidyBill("Basic", 6), 0);
pinned: basic, 2 classes: $30
pinned: basic, 6 classes: $54
CHANGED: basic, 9 classes: was $60, now $90
pinned: unlimited, 9 classes: $60
pinned: Basic, 6 classes: $0
// A teammate's tidier version, written from the comment.
function tidyBill(plan: string, classes: number): number {
switch (plan) {
case "unlimited": return 60;
case "basic": return 30 + Math.max(0, classes - 4) * 12;
default: return 0;
}
}
function pin(label: string, actual: number, expected: number): void {
console.log(actual === expected
? `pinned: ${label}: ${actual}`
: `CHANGED: ${label}: was ${expected}, now ${actual}`);
}
pin("basic, 2 classes", tidyBill("basic", 2), 30);
pin("basic, 6 classes", tidyBill("basic", 6), 54);
pin("basic, 9 classes", tidyBill("basic", 9), 60);
pin("unlimited, 9 classes", tidyBill("unlimited", 9), 60);
pin("Basic, 6 classes", tidyBill("Basic", 6), 0);
pinned: basic, 2 classes: $30
pinned: basic, 6 classes: $54
CHANGED: basic, 9 classes: was $60, now $90
pinned: unlimited, 9 classes: $60
pinned: Basic, 6 classes: $0
The tidier version reads better, and it would have raised a basic member's bill by $30. The pins caught it before any member did. In a real project each pin line is a test in your test framework (MSTest, JUnit, pytest, node --test), and a CHANGED line is a red test.
How to pin code down
- Pick the code you're about to change, not the whole system. Pin what the change could touch.
- Let the code tell you the answer. Write a test with an expected value you know is wrong, such as
0, and run it. The failure message says what the code really returned; paste that in as the expected value. You're recording, not guessing. - Pin the edges. Zero classes, exactly 4 and 5 (the boundary), a big number, and odd input like
"Basic". Surprises live at the edges; the cap only shows up at 8 classes or more. - Name the surprises, and ask. A test named "basic bills are capped at $60" turns a quirk into a question for the owner. If she says the capital-B $0 is a bug, fixing it is its own change, with the pin updated on purpose and the reason in the commit.
- Then change the code, running the pins after every small step. That's the next lesson.
When the output is long (a whole receipt, a report), tools can record all of it at once and compare it on every run; that's called approval testing, or snapshot testing. It's the same idea, in bulk.
When not to use it
- When the code already has good tests. Use them.
- When you're about to throw the code away whole. Pin what the replacement must match, not every line of the old one; Strangler Fig, later in this chapter, does this a piece at a time.
- When you can't run the code at all, because it builds its own database or reads the real clock. Then the first change is the smallest one that lets a test hand those in (Smells of Making), made carefully, by hand, and then pinned.
How often you'll meet it: often, in any job that has old code (our estimate).
Check yourself
2 questions to try on the lesson page.
So what
You can't keep what you never wrote down. Pin old code to what it does today, surprises included, and every change after that tells you exactly what it changed.