Open Source Java Testing & Assertion Libraries: AssertJ vs Hamcrest vs Google Truth

Choosing the right assertion library is one of the most impactful decisions a Java developer can make. While JUnit provides basic assertion methods, dedicated assertion libraries offer fluent, readable, and expressive APIs that dramatically improve test quality and developer experience for unit tests.

Three open source assertion libraries dominate the Java ecosystem: AssertJ, Hamcrest, and Google Truth. Each takes a different approach to writing test assertions — from rich fluent APIs to declarative matchers to simple, opinionated truth assertions.

Why Use a Dedicated Assertion Library?

Standard JUnit assertions like assertEquals, assertTrue, and assertNotNull work fine for simple cases, but they quickly become verbose and unreadable when dealing with complex objects, collections, and exception handling. A dedicated assertion library brings several advantages:

• Readability: Fluent assertion chains read like natural sentences
• Better error messages: Detailed failure descriptions that pinpoint exactly what went wrong
• Collection assertions: Rich APIs for lists, maps, and streams without verbose loops
• Type safety: Compile-time type checking that catches mistakes before tests run
• IDE support: Better autocomplete and navigation in modern IDEs

Comparison Table: AssertJ vs Hamcrest vs Google Truth

AssertJ: The Fluent Powerhouse

AssertJ’s fluent API is its strongest feature. Every assertion method returns an assertion object, enabling method chaining:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

@Test
void testEmployeeList() {
    List<Employee> employees = service.getActiveEmployees();
    
    assertThat(employees)
        .isNotEmpty()
        .hasSize(5)
        .extracting(Employee::getName)
        .contains("Alice", "Bob")
        .doesNotContain("InactiveUser");
    
    assertThat(employees)
        .filteredOn(e -> e.getSalary() > 50000)
        .extracting(Employee::getDepartment)
        .containsOnly("Engineering", "Data");
}

Key Strengths:

• Rich collection assertions (extracting, filteredOn, flatExtracting)
• Soft assertions that collect all failures before reporting
• Excellent error messages with diff-style comparisons
• First-class support for Java 8+ streams and Optionals

Maven/Gradle Setup:

1
2
3
4
5
6
7

<!-- Maven -->
<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <version>3.27.3</version>
    <scope>test</scope>
</dependency>

1
2

// Gradle
testImplementation 'org.assertj:assertj-core:3.27.3'

Hamcrest: The Matcher Foundation

Hamcrest pioneered the declarative matcher style that inspired both AssertJ and Truth. Its matchers are composable and self-documenting, making it especially valuable for complex conditional assertions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.*;

@Test
void testUserProperties() {
    User user = service.findById(1L);
    
    assertThat(user.getEmail(), containsString("@"));
    assertThat(user.getRoles(), hasItem("ADMIN"));
    assertThat(user.getCreatedAt(), 
        allOf(greaterThan(LocalDate.of(2020, 1, 1)),
              lessThan(LocalDate.now())));
    assertThat(user.getName(), 
        anyOf(equalTo("John"), startsWith("J")));
}

Key Strengths:

• Composable matchers (allOf, anyOf, not)
• Built into JUnit via assertThat()
• Huge ecosystem of custom matchers
• Language-agnostic (implementations for Python, C++, JavaScript)

Maven/Gradle Setup:

1
2
3
4
5
6

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>hamcrest</artifactId>
    <version>3.0</version>
    <scope>test</scope>
</dependency>

Google Truth: Simple, Opinionated, Powerful

Truth takes a minimalist approach. It provides a single entry point (Truth.assertThat) and focuses on making the common cases simple and the failure messages extremely clear:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import static com.google.common.truth.Truth.assertThat;

@Test
void testOrderProcessing() {
    Order order = processor.handle(cart);
    
    assertThat(order.getStatus()).isEqualTo("CONFIRMED");
    assertThat(order.getItems()).hasSize(3);
    assertThat(order.getTotal()).isGreaterThan(0.0);
    assertThat(order.getCustomerEmail()).contains("@");
    
    // Exception testing
    assertThrows(IllegalArgumentException.class, 
        () -> processor.handle(null));
}

Key Strengths:

• Extremely simple API — just one static import
• Exceptional failure messages with clear diff output
• Google-backed with regular releases and maintenance
• Protobuf support for gRPC service testing

Maven/Gradle Setup:

1
2
3
4
5
6

<dependency>
    <groupId>com.google.truth</groupId>
    <artifactId>truth</artifactId>
    <version>1.4.4</version>
    <scope>test</scope>
</dependency>

Code Examples: Side-by-Side

Comparing how each library handles common test scenarios:

Asserting a List of Objects

AssertJ:

1
2
3
4

assertThat(products)
    .hasSize(3)
    .extracting(Product::getPrice)
    .allSatisfy(price -> assertThat(price).isPositive());

Hamcrest:

1
2
3

assertThat(products, everyItem(
    hasProperty("price", greaterThan(BigDecimal.ZERO))
));

Google Truth:

1
2
3

for (Product p : products) {
    assertThat(p.getPrice()).isGreaterThan(BigDecimal.ZERO);
}

Testing Exceptions

AssertJ:

1
2
3

assertThatThrownBy(() -> service.process(null))
    .isInstanceOf(IllegalArgumentException.class)
    .hasMessageContaining("input must not be null");

Hamcrest: (with JUnit 5)

1
2
3
4
5

IllegalArgumentException ex = assertThrows(
    IllegalArgumentException.class,
    () -> service.process(null)
);
assertThat(ex.getMessage(), containsString("must not be null"));

Google Truth:

1
2
3
4
5

IllegalArgumentException ex = assertThrows(
    IllegalArgumentException.class,
    () -> service.process(null)
);
assertThat(ex).hasMessageThat().contains("must not be null");

Which Library Should You Choose?

Choose AssertJ if you value rich collection testing, want soft assertions to collect multiple failures at once, and prefer an extensive fluent API with auto-complete-friendly method chaining. It is the most feature-complete option and works exceptionally well in large enterprise codebases.

Choose Hamcrest if you need composable matchers that combine elegantly (allOf, anyOf), want cross-language consistency (same matcher concepts in Python, C++, and JavaScript), or are already using it through JUnit’s built-in support and don’t need migration.

Choose Google Truth if you prefer simplicity over features, want the clearest possible failure messages, or work on Android or with Protocol Buffers. Its straightforward API makes it the easiest to learn — team members can be productive in under an hour.

All three libraries are mature, well-maintained, and freely available under permissive open source licenses (Apache 2.0 for both AssertJ and Truth, BSD for Hamcrest). They can coexist in the same project, though most teams standardize on one for consistency.

For additional testing strategies, see our mutation testing guide and contract testing comparison. If you need API mocking for your integration tests, check out our API mocking tools guide.

Migration and Coexistence Strategies

If you are migrating from one assertion library to another, here are practical patterns for a smooth transition.

Migrating From JUnit Assertions to AssertJ

The most common migration path is from JUnit’s built-in assertions to AssertJ’s fluent API. Modern IDEs like IntelliJ IDEA have built-in inspections that detect JUnit assertions and offer to convert them to AssertJ automatically. For a manual migration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Before (JUnit 5)
assertEquals(3, list.size());
assertTrue(user.isActive());
assertNotNull(response.getBody());
assertEquals("admin", user.getRole());

// After (AssertJ — one command converts all)
assertThat(list).hasSize(3);
assertThat(user.isActive()).isTrue();
assertThat(response.getBody()).isNotNull();
assertThat(user.getRole()).isEqualTo("admin");

The IntelliJ plugin “Assertions2AssertJ” automates this for entire test suites, converting thousands of assertions in seconds.

Mixing Libraries During Transition

If your team is gradually adopting a new assertion library, you can mix them in the same codebase during the transition period. Both AssertJ and Hamcrest (and Truth) work by throwing AssertionError, which JUnit catches regardless of the library. The key practice is to standardize within individual test classes — do not mix libraries in the same test method or class, as this creates confusing failures and makes code review harder:

1
2
3
4
5
6
7
8

// Class-level consistency is fine
class UserServiceTest {
    // All tests in this class use AssertJ
}

class OrderServiceTest {
    // All tests in this class use Hamcrest
}

Hamcrest Matchers in AssertJ

AssertJ can directly use Hamcrest matchers through its assertThat(...).matches(...) method, allowing you to leverage existing custom Hamcrest matchers during a migration without rewriting them:

1
2
3
4

import static org.assertj.core.api.Assertions.assertThat;
import static com.mycompany.CustomHamcrestMatchers.isValidIsoDate;

assertThat(order.getCreatedAt()).matches(isValidIsoDate());

This interoperability means you can adopt AssertJ for new tests while your custom Hamcrest matchers continue working.

Continuous Integration Considerations

When switching assertion libraries in a CI pipeline, update your build configuration to include the new dependency and update any custom test listeners or report generators. AssertJ and Truth both produce structured AssertionError messages that integrate with JUnit’s XML test reports. Hamcrest’s Description objects can also be transformed for CI reporting. Ensure your CI dashboard correctly parses failure messages from whichever library you standardize on.

FAQ

Can I use more than one assertion library in the same project?

Yes, technically you can include multiple assertion libraries, but it is not recommended. Different assertion APIs in the same test suite confuse team members and make code reviews harder. Pick one as your standard and use it consistently. If you must test drive a new library, do it in a separate branch or experimental module.

How do AssertJ soft assertions work?

Soft assertions collect all assertion failures during a test and report them together at the end, unlike standard assertions that stop at the first failure. Use SoftAssertions softly = new SoftAssertions(); then call softly.assertThat(...) for each check, and finally softly.assertAll(); to trigger the combined error report. This is invaluable for testing multiple properties of the same object without losing visibility into subsequent failures.

Is Google Truth related to JUnit’s Truth?

No — Google Truth (com.google.truth:truth) and JUnit are separate projects. Truth was originally developed at Google for internal use and later open sourced. It integrates smoothly with JUnit (both 4 and 5) as a drop-in replacement for JUnit’s built-in assertions. The JUnit team maintains its own assertion API, but Google Truth is an external library maintained by Google.

Do these libraries work with TestNG?

All three work with TestNG. AssertJ and Truth are assertion libraries and framework-agnostic — they just throw AssertionError on failure, which both JUnit and TestNG catch. Hamcrest matchers are also framework-agnostic. The only JUnit-specific feature is assertThrows, which Truth and AssertJ both provide as utility methods that work independently of the test runner.

Which library has the best IDE autocomplete support?

AssertJ has the richest autocomplete experience due to its fluent API returning specific assertion types (StringAssert, ListAssert, MapAssert). This means your IDE only shows relevant methods for the type you are asserting. Hamcrest matchers are static method imports with broader applicability, so autocomplete shows all matchers regardless of context. Truth sits in the middle — simpler than AssertJ but still type-aware.

How do I write custom assertions for my domain objects?

All three support custom extensions. In AssertJ, extend AbstractAssert<MyAssert, MyDomain> and add fluent methods returning MyAssert. In Hamcrest, extend TypeSafeMatcher<MyDomain> and override matchesSafely(). In Truth, implement Subject.Factory<MySubject, MyDomain> and add assertion methods. AssertJ’s approach is generally the most ergonomic for complex domain objects.

💰 想测试你的市场判断力？我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台，从大选结果到技术监管时间线，什么都可以押注。和赌博不同，这是真正的信息市场：你懂的信息越多，胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册：Polymarket.com