AssertJ is an open source Java library for writing fluent assertions in your test code. It’s an alternative to built-in assertions from the Junit testing framework or matchers from the Hamcrest library. It can help you write assertions that are more readable and closer to natural language. AssertJ API is also designed to be easily discoverable through IDE code completion.

Benefits of AssertJ

The most commonly used test assertions in Java are the ones from the Junit library, like assertEquals. The order of parameters in these assertions is important, but it is quite easy to get it wrong. The assertion will fail as expected, but it will produce a confusing error message:

assertEquals("actual", "expected");

org.junit.ComparisonFailure:
Expected :actual
Actual :expected

AssertJ helps you to write assertions that are much closer to natural language. This makes them more readable and reduces the chance of writing them wrongly:

assertThat("actual").isEqualTo("expected");

Another benefit of AssertJ is the fluent interface which enables the chaining of multiple assertions. Instead of writing multiple statements, you can write it like this:

assertThat("Foo")
  .isNotNull()
  .startsWith("F")
  .endsWith("o")
  .contains("x")
  .isEqualToIgnoringCase("foo");

This will fail with a helpful message:

java.lang.AssertionError:
  Expecting:
  <"Foo">
  to contain:
  <"x">

Built-in assertions

AssertJ provides built-in assertions for many different types of objects. We’ve already seen assertions on String objects. Here is an example of an assertion on integers:

assertThat(123)
  .isGreaterThan(122)
  .isLessThan(124)
  .isBetween(100, 200);

Assertions on lists are quite powerful – this example shows how to filter a list of User objects on the user role and extract user names (using Java 8 features):

assertThat(users)
  .filteredOn(user -> user.getRole().equals("ADMIN"))
  .extracting(User::getName)
  .contains("user1", "user2");

Assertions on exceptions are also supported:

assertThatThrownBy(() -> { throw new RuntimeException("error"); })
  .isInstanceOf(RuntimeException.class)
  .hasMessageContaining("error");

Custom assertions

It’s also possible to write your own assertions – this is especially useful for your core domain model classes. You can write custom assertions manually or use the provided assertions generator. This will result in a domain specific language for use in tests. An example usage of custom assertions:

assertThat(user)
  .hasRole("ADMIN")
  .hasName("user1");

Installation

If you want to try the AssertJ library, you can get it via Maven:

<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <version>3.11.1</version>
  <scope>test</scope>
</dependency>

Or if you use Gradle:

testCompile("org.assertj:assertj-core:3.11.1")