AssertJ — Fluent Assertions Library for Java and JVM Testing

Introduction

AssertJ is a Java assertion library that replaces JUnit's built-in assertEquals / assertTrue with a fluent, type-safe API. Tests written with AssertJ read like natural language, and when they fail the error messages describe exactly what went wrong — including the expected and actual values in context. AssertJ works with JUnit 4, JUnit 5, and TestNG.

What AssertJ Does

• Provides fluent assertions for strings, collections, maps, dates, exceptions, and custom types
• Generates descriptive failure messages that include full context without extra effort
• Supports soft assertions that collect multiple failures before reporting them
• Enables custom assertion classes for domain objects via a code generator
• Covers Java 8+ features including Optional, Stream, CompletableFuture, and Path

Architecture Overview

AssertJ's API is organized around typed assertion classes. When you call assertThat(value), the library selects the appropriate assertion class based on the value's type — StringAssert for strings, ListAssert for lists, and so on. Each assertion method returns this, enabling method chaining. Conditions and filters extend the DSL for complex checks. A code generator can produce project-specific assertion classes from your domain model, so you can write assertThat(order).hasStatus(SHIPPED) directly.

Self-Hosting & Configuration

• Add assertj-core as a test dependency in Maven or Gradle
• Static import org.assertj.core.api.Assertions.assertThat in your test classes
• Chain assertion methods for readable checks: assertThat(result).isNotNull().startsWith("OK")
• Use SoftAssertions to collect all failures in a test before stopping
• Optionally generate custom assertion classes with the AssertJ assertions generator

Key Features

• Type-safe fluent API covers 100+ assertion methods across all standard Java types
• Rich collection assertions including filtering, extracting fields, and recursive comparison
• Soft assertions collect all failures in a test method instead of stopping at the first
• Recursive comparison compares nested object graphs field by field
• IDE auto-complete makes discovering assertion methods effortless

Comparison with Similar Tools

• JUnit assertions — Basic assertEquals/assertTrue; AssertJ is far more expressive and produces better error messages
• Hamcrest — Matcher-based assertions; AssertJ's fluent API is more discoverable via IDE auto-complete
• Truth (Google) — Similar fluent style; AssertJ has broader type coverage and is more widely adopted
• FEST-Assert — Predecessor to AssertJ; no longer maintained, AssertJ is its direct successor
• Kotest assertions — Kotlin-first; AssertJ covers Kotlin via JVM interop and is standard in Java projects

FAQ

Q: Can I use AssertJ alongside JUnit 5 assertions? A: Yes. AssertJ is a library, not a test framework. You can mix AssertJ and JUnit assertions in the same test class.

Q: What are soft assertions? A: Soft assertions collect all failures in a test before throwing. Use SoftAssertions.assertSoftly(softly -> { softly.assertThat(...); }) to check multiple conditions without short-circuiting.

Q: Does AssertJ support comparing nested objects? A: Yes. Use assertThat(actual).usingRecursiveComparison().isEqualTo(expected) to compare object graphs field by field.

Q: Can I create custom assertion classes for my domain objects? A: Yes. The AssertJ generator creates typed assertion classes from your POJOs, enabling domain-specific assertions like assertThat(user).hasEmail("a@b.com").

Sources

• https://github.com/assertj/assertj
• https://assertj.github.io/doc/