Ace8 is the modernization practice of AceMQ.24/7 support from AceMQ after go-live
Book an Assessment
GuideGuide

Characterization tests: pin legacy behaviour before you change it.

A characterization test records what the code does today, right or wrong, so you can tell when a change alters it.

AceMQ engineering team3 min readEngineer-reviewed

Stacks we work in

  • Java
  • JUnit
  • Spring Boot
  • Kubernetes
  • PostgreSQL
  • Kafka
  • Docker
  • Terraform
  • GitHub Actions
  • Java
  • JUnit
  • Spring Boot
  • Kubernetes
  • PostgreSQL
  • Kafka
  • Docker
  • Terraform
  • GitHub Actions
The short answer

Characterization testing means writing tests that capture what existing code actually does, not what it should do. You run the code, record the output as the expected value, and from then on any change in behaviour fails a test. The term comes from Michael Feathers' book Working Effectively with Legacy Code.

ServiceLegacy application modernizationWe write tests first, change code in small slices, and keep the old system running until the new one has earned the traffic.See the service

01 · Definition

What is a characterization test?

A characterization test documents the current behaviour of a piece of code, including its bugs.

  1. 01

    The assertion matches what the code does now. A normal test starts from a specification; this one starts from the running system.

  2. 02

    Michael Feathers introduced the term in Working Effectively with Legacy Code (2004). His working definition of legacy code is code without tests, and his answer to it is to add tests that describe reality before anyone refactors. Without them nobody can show a change kept behaviour intact.

02 · Comparison

How is a characterization test different from a unit test?

Unit test (new code)Characterization test (legacy code)
Expected value comes fromThe requirementRunning the code today
AnswersIs it correct?Did it change?
A failure meansThe code is wrongBehaviour moved; decide if that was intended
WrittenBefore or with the codeBefore the first modification
LifetimePermanentOften temporary, until proper tests replace it

03 · How to

How do you write characterization tests?

Work on one unit at a time, with the part you are about to change first.

Step 01 of 05

Get the code into a test harness

Instantiate the class or call the function from a test. If it will not construct because of hard-wired dependencies, find a seam, a place where behaviour can be altered without editing the code at that place, and use it.

04 · Example

What does a characterization test look like in Java?

Take an illustrative legacy method InvoiceCalculator.total(Order order) that nobody fully understands.

  1. 01

    In a JUnit 5 test you build an order with three lines and a discount code, call total(order), and assert assertEquals("0.00", result.toPlainString()). It fails and the report says the actual result was 127.35.

  2. 02

    You change the expected value to 127.35 and the test passes. You repeat with an empty order, a null discount code and a refund line. You now have a net: if a later refactor makes total return 127.34, a test fails and you must decide whether that is a fix or a regression. This example is illustrative; the numbers are not from a real system.

  3. 03

    For output too large to paste, such as a generated report, use approval testing: save the full output to a file the first time, and compare each later run against that file.

05 · Limits

When should you stop, and what do these tests not tell you?

Stop when the code you plan to change is covered along the paths that matter.

  1. 01

    Characterization tests do not tell you the behaviour is correct, only that it is unchanged, so a recorded bug stays a bug until someone decides to fix it.

  2. 02

    They can also be brittle where output includes timestamps, random ids or ordering that is not guaranteed. Pin or strip those values before you assert. Replace characterization tests with intent-revealing unit tests as you learn what the code is for.

06 · In practice

Where do characterization tests fit in a modernization?

They are the first step of any refactor or upgrade, because they define what "same" means.

  1. 01

    Our legacy application modernization work starts with tests around the code before AI-assisted changes are made, and AceMQ engineers review every change.

  2. 02

    If the test gap is large, it is also a measure of technical debt and the first thing the modernization assessment sizes. For the wider option set, see legacy system modernization approaches.

FAQ

Frequently asked questions

Short answers to what buyers ask first. Something else on your mind? Ask an engineer.

Writing tests that record what existing code currently does, so any later change in behaviour is detected. The term is Michael Feathers'.

Start here

Know the cost before anything moves.

A fixed-price assessment gives you the inventory, the risk score and a phased plan. Scope and cost are fixed before the migration starts.

Inventory
Every application, its stack and what it depends on.
Risk score
Where a change is likely to break, ranked.
Phased plan
What moves first, which tools lead, and the fixed price.

Get in touch

Talk to a modernization engineer.

Tell us what you run today. An engineer, not a sales script, replies within one business day.

305-204-2607info@ace8.io

66 W. Flagler St. 9th Floor
Miami, FL 33130

What are you moving off? *

Fixed price. Scope and cost before any migration starts.