Secure Code Warrior

Make unit tests readable with Sensei and AssertJ

Implement unit test coding guidelines uniformly and consistently

Developers create and test their own code with various methods. One such method is unit testing - a very popular method of testing the smallest parts of one’s own code. When written well, unit tests can help to improve the quality of your code, as well as reduce costs and development time. Whether done as part of test-driven development (TDD) or not, unit testing is a key part of modern development practices and its importance has led to the creation of many testing frameworks.

But in the absence of a proper testing framework and guidance, unit tests can become complex and unreadable as the focus shifts to coverage and quantity rather than quality and readability. This is especially true in a large and active codebase with many unit tests.

A good test framework helps create good readable tests that are simple and focus on quality testing. They also help document the way to use your code as well. One such framework is AssertJ.

AssertJ is a fluent API for writing unit tests in Java. It lets you write test assertions that read like English, with context-aware autocomplete. If you have a large number of tests and need to improve their readability, you may wish to migrate all of them to AssertJ and also ensure that all future tests are taking full advantage of AssertJ.

But complete migration can take an enormous effort and time to do manually and so it is often skipped or put off for other development tasks. So we created Sensei - a highly customizable IntelliJ plugin that can help migrate your current unit tests to use AssertJ as well as enable all future tests to be written the right way. This is done with a number of recipes (rules) already created for you by Sensei’s development team. Sensei makes it easy to perform a one-time migration or take the approach of doing incremental migrations to AssertJ, one test at a time. Once you have moved to AssertJ, the recipes continue to help developers apply quick fixes as they write unit tests so that your unit tests continue to be uniform, standard and consistent across the entire codebase.

About Sensei

Sensei is a highly customizable IntelliJ plugin to scan and fix undesirable code as you type - with hundreds of downloadable code transformations and migration recipes (rules) as well as an in-built ability to craft your own. With Sensei, developers can remediate bad code patterns as they type so that they can deliver quality code faster and, ultimately write it in a consistent and standard way across teams and projects.

Here is an example of a sample migration that might help you see how Sensei makes it painless to migrate your unit tests to use AssertJ.

Why is AssertJ a great framework to write unit tests

Instead of writing a test like this JUnit assertion:

Assert.assertEquals(3, x.size()); // assert that 3 is x's size.

you can write this with AssertJ:

assertThat(x).hasSize(3); // assert that x has size 3.

This means you can read the assertion left to right like an English sentence, and it’s clear which is the expectation (in this case, the size 3). How many times have you written an assertion the wrong way around, like this?

Assert.assertEquals(x.size(), 3);

These are just simple examples. The more complex your checks and assertions, the more AssertJ helps you make your tests simple and readable. It works nicely with your IDE’s auto-complete. As soon as you type:


it will pop up with all the things you can check, based on the type of myResult. If it is a collection, you can check its contents, size, whether it contains certain values or types, and so on.

Out of the box, AssertJ has support for primitives and their boxed types, Atomic types, Collections, arrays, Maps, Dates, java.time, Futures, Files/Paths, InputStreams, Throwables, and URLs. And if you have a favorite custom Matcher for Hamcrest, you can use it with AssertJ via HamcrestCondition.

Readable unit tests make it easy for developers to read code in normal English and therefore make it easy to spot mistakes as well as increase coverage - which makes AssertJ an indispensable framework for good Java unit tests.

Recipes to move legacy unit tests to AssertJ

We have written a cookbook to help you write consistent code with AssertJ. It can help you migrate your assertions to AssertJ from any of these frameworks: JUnit 3, JUnit 4, JUnit 5 and FEST-Assert.

This cookbook can be configured in Sensei for immediate use and you can find installation instructions for Sensei here.

Write better unit tests as you code - improving JUnit quality progressively

The Sensei cookbook for AssertJ doesn’t just help you to migrate from other frameworks. It has some recipes which can help you to improve your test writing, break old habits, and write more idiomatic AssertJ tests.

For instance, let’s say you have written a test which looks like this:


Perhaps you even migrated it using one of the migration recipes above, from this JUnit-style assertion:

assertTrue(collection.size() == 1);

The Sensei cookbook for AssertJ has a recipe that can also detect this old style of assertion, and offer to convert it to this:


Another recipe can convert the following from:


to this:


A one-time migration and uniform coding practices across teams - with Sensei

We can see from our examples above, the manual migration of unit tests to use AssertJ can involve a lot of effort and time that is best spent on writing better tests. By using Sensei, you can easily migrate your unit tests to AssertJ with confidence. You can perform a one-time migration, or migrate individual tests to AssertJ as you come across them. Sensei provides this type of flexibility that makes code migrations less painful.

Unit test migration is just one example of the many ways Sensei can be used to write consistent code across your projects. You can always be on the lookout for anti-patterns or certain manual code transformations that you frequently come across in pull requests or as you code yourself. If you have a set of coding guidelines that are often missed by developers then you could convert the guidelines into recipes - enabling developers to apply approved code transformations with confidence.

If you have any questions, we’d love to hear from you! Join us on Slack at: