Skip to main content

Characterization Tests: Locking Down Legacy Behavior Before You Understand It

When you inherit a legacy system that has to be modernized, the usual instinct is to read the code until you understand it and then write tests. In practice that order often fails. The code works in production, nobody is sure why, and your understanding is a set of hypotheses. A better first step is to record what the code actually does today, then change it safely.

Tests written for that purpose are called characterization tests, a term popularized by Michael Feathers in Working Effectively with Legacy Code. They document observed behavior, not intended behavior, so they pass even if the behavior is wrong. Their job is to make any change in behavior visible.

Why "understand first, test later" breaks down

Classic test-first thinking assumes you know the requirements. In a legacy system the requirements are implicit, scattered across service classes, stored procedures and configuration, and shaped by years of patches. If you write tests from your reading of the code, you are testing your assumptions. A characterization test asks the system instead: call the method with a realistic input, take the output as the expected value, and from then on any change that alters the output fails the test and forces a decision.

Step 1: Pick the seam you are about to change

Do not try to characterize the whole system. Start with the method or class you intend to refactor next, and write tests only around that seam. Characterize first, refactor second.

Step 2: Record the observed output

Imagine a long invoice calculation method that nobody fully understands. Call it with a production-like input and write down what comes back:

[TestFixture]
public class InvoiceServiceCharacterizationTests
{
    [Test]
    public void CalculateTotalAmount_StandardInvoice_MatchesObservedBehavior()
    {
        var invoice = new Invoice
        {
            InvoiceId = 12345,
            LineItems = new List<LineItem>
            {
                new LineItem { Quantity = 2, UnitPrice = 50.00m, TaxRate = 0.08m },
                new LineItem { Quantity = 1, UnitPrice = 120.00m, TaxRate = 0.08m }
            },
            DiscountCode = "SUMMER10"
        };

        var result = new InvoiceService().CalculateTotalAmount(invoice);

        // Values captured by running the existing code, not derived from a spec
        Assert.That(result.DiscountAmount, Is.EqualTo(22.00m));
        Assert.That(result.TaxAmount, Is.EqualTo(15.84m));
        Assert.That(result.TotalAmount, Is.EqualTo(213.84m));
    }
}

The test does not claim 213.84 is correct. It claims that is what the system returns today. If a refactor changes it to 213.50, the test fails and you investigate: intentional change, or regression?

For methods that return large or complex objects, consider snapshot or approval testing (for example the Verify library). It serializes the output to a file and compares future runs against it, which is much less tedious than writing dozens of assertions by hand.

Step 3: Handle dependencies pragmatically

Legacy methods often call databases, static helpers or external services. Mocking everything requires understanding what each dependency does, which defeats the point. Prefer the smallest change that makes the test repeatable:

  • Database: run the test against a local or containerized database with a known dataset.
  • External service: record a real response and replay it through a stub.
  • Static helper: wrap it in a thin interface so a test can substitute it. This is a small, low-risk edit to the production code.
[Test]
public void CalculateTotalAmount_WithRepositoryDiscount_MatchesObservedBehavior()
{
    var repo = new Mock<IDiscountRepository>();
    repo.Setup(r => r.GetDiscountByCode("SUMMER10"))
        .Returns(new Discount { Code = "SUMMER10", Percentage = 0.10m });

    var service = new InvoiceService(repo.Object);

    var invoice = new Invoice
    {
        InvoiceId = 12345,
        LineItems = new List<LineItem>
        {
            new LineItem { Quantity = 2, UnitPrice = 50.00m, TaxRate = 0.08m }
        },
        DiscountCode = "SUMMER10"
    };

    var result = service.CalculateTotalAmount(invoice);

    Assert.That(result.TotalAmount, Is.EqualTo(97.20m));
}

Keep stubs shallow: stub only what the code is known to call. If the real dependency has side effects or hidden state, these tests will not catch them. That is acceptable at this stage. They will become true unit tests later.

Step 4: When the tests reveal a bug

Sometimes the recorded behavior is plainly wrong: a rounding rule that rounds the wrong way, a tax applied twice, a discount applied after tax instead of before. You have just written a passing test that asserts a bug. Decide deliberately:

  • If the bug is serious and the stakeholders agree, fix it and update the test in the same change.
  • If it has been in production a long time and fixing it has side effects (data migration, customer communication), leave a comment, open a separate issue, and finish the refactor first.

Mixing a behavior fix into a structural refactor makes both harder to review and to roll back.

Step 5: Treat the tests as scaffolding

  1. Write characterization tests for the seam.
  2. Refactor while keeping them green.
  3. Extract smaller methods and cover them with focused unit tests that assert intended behavior.
  4. When the unit tests cover the behavior, reduce or delete the characterization tests.

If a characterization test fails unexpectedly during a refactor, stop and find out why before moving on. The suite acts as a ratchet: it keeps you from sliding backward while the design improves.

Practical rules

  • Use realistic inputs. Synthetic data tends to miss the edge cases that years of patches were written for.
  • Characterize only what you are about to change.
  • Accept some integration-test traits early; isolation comes later.
  • Run them in CI and investigate every failure before merging.
  • Add a comment saying the test records observed behavior, so nobody mistakes it for a specification.

Characterization tests are not elegant, and they are not the tests you would write on a greenfield project. They are what make modernization incremental instead of a rewrite that never ships.

Comments