Clean Code - 5 Tips on Writing Clean Tests

5 practical tips to improve the quality of your tests

50% OFF - The Complete TDD course

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.

Motivation

In TDD, we use tests not only for verification but also to design software. Writing clean tests is as important as writing clean code because they shape the maintainability of your system.

Clean tests are your safety net, your documentation, and your design blueprint—all rolled into one. In this post, I will give you 5 practical tips to help you write clean tests.

Use a Naming Template

A clean test name serves two things:

• when a test fails, we can immediately tell what is broken

• it provides a clear entry point for the business behaviors

One of the most effective naming templates for tests is the ShouldWhen template. It has two forms:

• {Action}_Should_{Expectation}_when_{Precondition}

• Should_{Expectation}_when_{Precondition}

First, let’s see a few bad examples for unclean test names:

Now, let’s improve the examples above using the ShouldWhen template:

Structure With The AAA Pattern

The Arrange-Act-Assert (AAA) pattern is a simple and effective way to organize your test. It breaks the test into three clear steps:

1. Arrange: Set up the necessary test data, dependencies, and environment for the system under test.

2. Act: Execute the system under test, such as calling a function, making a REST API call, or interacting with a module.

3. Assert: Verify that the system behaves as expected by checking return values, final state, dependency interactions, or expected errors.

In practice, these steps are usually separated by new lines for readability. For more complex tests, adding comments to label each part is a good way to improve clarity.

Here is a test without the AAA pattern applied:

Now let’s look at the same test by applying the AAA pattern:

It reads way much better, doesn’t it?!

Clean Assertion

The assertion is the heart of every test. It’s where you prove the code delivers on its promise. A strong assertion not only validates behavior but also encapsulates domain insights, ensuring your tests are meaningful.

Avoid raw assertions! They make it harder to understand what's being tested:

Instead, express the business behavior with clean assertions:

F.I.R.S.T. Principle

The golden rule for great tests is to follow the F.I.R.S.T. principle. This means tests should be:

• Fast: Run quickly to maintain short feedback loops.

• Independent: Not rely on other tests.

• Repeatable: Produce the same result regardless of the environment.

• Self-validating: Clearly show success or failure without manual checks.

• Timely: Written at the right time, ideally before the code.

Follow these rules, leading to clean tests.

Meaningful Test Data

Good tests rely on meaningful data. Use real-life examples that reflect actual scenarios, ensuring the data is representative. It keeps the documentation clean and easy to understand. It is all about making your tests more relatable to your colleagues and your future self.

Meaningless data

Meaningful data

Summary

Clean code starts with clean tests including a standardized naming template, the AAA structure, clean assertions, the F.I.R.S.T. principle, and meaningful test data.

There are many other tips you can use to produce quality tests. If you want to learn more, you can find them in my TDD course, including:

• The fundamentals of Test-Driven Development (TDD)

• 3 real-world examples in C#, TypeScript and Rust

• Using TDD to design high-quality software

• The two schools of testing with the 5 test doubles

• Testing legacy code and refactoring best practices

Get instant access by clicking here.