How To Refactor Legacy Code

The art of making your code testable, testing it effectively, and refactoring it like a pro

Daniel Moka

Apr 12, 2025

Are you ready to master Clean Code, Testing and Test-Driven Development (TDD)?

I recently launched a complete TDD course containing everything you need to craft high-quality software.

Now there is a 50% OFF for the course

Get instant access by clicking here.

Get Instant Access

Motivation

“Legacy code is simply code without tests.” - Michael C. Feathers

Most legacy code isn’t bad code. It’s just untested. Untested code is scary. You can’t change it with confidence. You fear breaking things. It slows down development.

But there’s a way out of this trap. A proven strategy I’ve used in both startups and corporate environments to turn messy legacy code into clean, testable, and maintainable systems.

Here’s my 6-step approach to refactoring legacy code;

The Ultimate Refactoring Strategy

Break Dependencies
Characterization testing
Approval testing
Property-based testing
Functional testing to reach 100% coverage
Refactor the code

Step 1: Break Dependencies

Legacy code is hard to test. Your first goal isn’t to add tests everywhere.
Your first goal is to make your code testable. Dependencies are the #1 reason code is hard to test. External calls like APIs, databases, or message queues make testing hard.

The first step is to look for places in the code where you can change behavior without changing structure. Look at this code:

It has the FileReader dependency hardly coupled. Our goal is to break this dependency and use test doubles - mocks, stubs, fakes - with dependency injection:

Your goal should be to break all the dependencies in your legacy code, with two important notes:

If the dependency is fast → use the real one, it leads to more realistic tests
If the dependency is essential for testing business logic → use the real one, it leads to more meaningful tests

Step 2: Characterization Testing

Before refactoring, you need to understand legacy code. The goal of characterization testing is not about finding bugs. The goal is to understand behaviors.

Use characterization tests when:

The code is too complex to reason about
There is no documentation
There are no existing tests

Let’s say you have this code snippet you don’t know anything about:

The best way to figure out is to write characterization tests around it.

Steps:

Write a test that calls the legacy code

Add an assertion you think should fail.

Execute test to observe behavior

It will likely result in an error like:

Expected formattedText to be <null>, but found "plain text".

Update the test to capture the behavior

Repeat this cycle with new tests until you fully understand the code.

By doing so you both learn about the business logic and document behaviours with automated tests.

Step 3: Approval testing

Writing assertions for complex objects is painful. Approval testing makes it easier. Instead of checking every field manually, you capture the full output once, then compare future runs against it.

How it works:

Generate output from your code
Approve it as correct (store it in a file)
On future runs → compare new output vs approved

Example of a normal unit test:

Problems with this test:

Hard to maintain
If data structure changes → 5 places to update.
Tiresome to write assertions for large data structure

Here is the same test with an approval test:

Just one line. It asserts the whole data structure in a text format. On the first run, it generates a file like this:

ExportToXml_Should_Work.received.txt

When you approve it manually, then it becomes:

ExportToXml_Should_Work.approved.txt

Then in any future run, you just compare the new received vs approved. If there is a change, you probably broke some functionality.

This practice works perfectly for outputs like JSON, HTML, or text reports. You can find approval testing libraries in almost any programming language, check them out!

⚠️ A word of caution

Approval tests are temporary tools. They often lead to fragile tests. They slow you down in the long run. Once your code is clean, refactored, and covered by solid functional tests, delete most of them without regret.

Step 4: Property-based testing

This is my favorite type of testing. Why? Because bugs don’t hide in the happy paths. They hide in the edge and corner cases.

Property-based testing helps you generate a large number of test cases with random inputs, then verifies that certain behaviors always hold true no matter what.

It’s super handy because it captures the key behaviors of your app - the things that should never break when you refactor.

To learn more about property testing, I wrote a full article on this topic, click here to read more.

Step 5: Go for 100% coverage

Aim for ~100% code and behavior coverage. Why so strict? Because anything less leaves room for bugs when you refactor your code. You want maximum confidence. You want a test suite you fully trust. Sure, 100% coverage is almost impossible. But your goal should be to get as close to that as possible.

Use tools like:

Code Coverage → shows what lines of code are uncovered
Mutation Testing → shows what behaviors are untested (even if your code is covered)

Run these tools iteratively and keep adding functional tests until you maximize the coverage results. To learn more about Mutation Testing, check out my recent article about it.