AssertJ - Getting Started with AssertJ

[Last Updated: Mar 3, 2026]

AssertJ is a Java library that provides a rich set of fluent assertions. Unlike JUnit's built-in assertEquals or Hamcrest matchers, AssertJ lets you chain multiple assertions on the same object and produces highly readable error messages when tests fail.

The core idea is simple: pass the object under test to Assertions.assertThat(), then chain assertion methods. AssertJ automatically infers the appropriate assertion type based on the object passed, providing access to type-specific assertion methods.

In other words, Assertions provides overloaded assertThat() methods. When you call assertThat() with a particular type, the corresponding implementation of org.assertj.core.api.Assert is returned, which includes chainable methods specific to that type. For example, calling assertThat("my string") returns a StringAssert object, allowing you to chain string-specific assertions like startsWith(), contains(), or endsWith().

Why AssertJ?

Traditional JUnit assertions like assertEquals(expected, actual) are easy to misorder (expected vs actual confusion) and produce terse error messages. AssertJ solves both problems: the assertThat(actual).isEqualTo(expected) syntax reads naturally, and failure messages clearly describe what was expected versus what was found.

Adding AssertJ to Your Project

For Maven, add the following dependency to your pom.xml:

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

For Gradle:

testImplementation("org.assertj:assertj-core:3.27.7")

If you use Spring Boot, spring-boot-starter-test already includes AssertJ, so no extra dependency is needed.

Entry Point

A single static import gives you access to all AssertJ assertion methods:

import static org.assertj.core.api.Assertions.*;

Example

package com.logicbig.example;

import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;

public class GettingStartedExample {

    @Test
    void myTest() {
        // Basic string assertion
        assertThat("AssertJ").isNotNull()
                             .startsWith("Assert")
                             .endsWith("J")
                             .contains("sert");
        System.out.println("String assertions passed");

        // Basic number assertion
        assertThat(42).isGreaterThan(10)
                      .isLessThan(100)
                      .isEqualTo(42);
        System.out.println("Number assertions passed");

        // Boolean assertion
        assertThat("hello".isEmpty()).isFalse();
        System.out.println("Boolean assertion passed");
    }
}

Output

$ mvn clean test -Dtest=*
[INFO] Scanning for projects...
[INFO] 
[INFO] ------------< com.logicbig.example:assertj-getting-started >------------
[INFO] Building assertj-getting-started 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- clean:3.2.0:clean (default-clean) @ assertj-getting-started ---
[INFO] Deleting D:\example-projects\assertj\assertj-getting-started\target
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ assertj-getting-started ---
[INFO] skip non existing resourceDirectory D:\example-projects\assertj\assertj-getting-started\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ assertj-getting-started ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ assertj-getting-started ---
[INFO] skip non existing resourceDirectory D:\example-projects\assertj\assertj-getting-started\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ assertj-getting-started ---
[INFO] Changes detected - recompiling the module! :source
[INFO] Compiling 1 source file with javac [debug target 17] to target\test-classes
[INFO] 
[INFO] --- surefire:3.2.5:test (default-test) @ assertj-getting-started ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.GettingStartedExample
String assertions passed
Number assertions passed
Boolean assertion passed
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.188 s -- in com.logicbig.example.GettingStartedExample
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.829 s
[INFO] Finished at: 2026-03-03T11:05:01+08:00
[INFO] ------------------------------------------------------------------------

Conclusion

The output confirms that chained assertions work sequentially — each assertion in the chain is evaluated, and if any fails, an informative message pinpoints the exact failure. This example demonstrates how AssertJ's fluent API makes test assertions both expressive and easy to diagnose.