From Coding to Cooking to Coins:
Antonio Lagnada's Blog on Software, Music, Food, and Finance

Java • AssertJ vs Hamcrest Assertion Frameworks

Post Date: 27 Oct 2023


When working with testing frameworks like JUnit or TestNG, selecting the right assertion framework can significantly enhance the readability of your test code and improve the overall quality of your tests. Two of the most popular Java assertion frameworks are AssertJ and Hamcrest. In this article, we will provide an in-depth comparison of these two frameworks, highlighting their respective features, strengths, and examples of how to implement them in your test cases.

Embed from Getty Images

AssertJ Assertion Framework

AssertJ is a powerful and flexible Java library designed to enhance the readability of your test code by providing a rich set of assertion methods. These methods allow you to write more concise and human-readable assertions for your tests.

Features of AssertJ

  1. Fluent API - AssertJ provides a fluent API that makes it easy to chain multiple assertions together, creating a more readable and concise test case.
  2. Custom Assertions - With AssertJ, you can create custom assertions tailored to your specific needs, providing greater flexibility in your test cases.
  3. Wide Range of Assertions - AssertJ is renowned for its extensive array of assertions, meticulously designed to cater to various data types and testing needs. It provides a comprehensive set of assertions for common data types like objects, arrays, lists, and maps, as well as for more complex data structures.
  4. Detailed Error Messages - AssertJ generates good error messages that help to quickly identify the cause of a failed test.
  5. Allows for custom error messages - enables developers to create personalized error messages that are specific to each test case
  6. String Substitutions - Supports string substitutions in error messages, providing a more flexible and tailored approach to communicating test failures.

Example of AssertJ

Consider a scenario where you need to validate that a list of strings contains specific elements:

List<String> languages = Arrays.asList("Java", "Python", "C++");


Hamcrest Assertion Framework

Hamcrest is another popular Java assertion framework known for its use of matcher objects to create readable assertions. This framework is also compatible with JUnit and TestNG, and provides a different approach to writing assertions.

Features of Hamcrest

  1. Matcher Objects - Hamcrest uses matcher objects to create expressive and readable assertions.
  2. Composability - Hamcrest allows you to compose multiple matcher objects together to create more complex assertions.
  3. Wide Range of Matchers - Hamcrest provides a wide range of predefined matcher objects that can be used to validate different types of data.
  4. Custom Assertions - With Hamcrest, you have the ability to craft custom assertions that are precisely aligned with your unique requirements.
  5. Allows for custom error messages - enables developers to create personalized error messages that are specific to each test case

Example of Hamcrest

In the same scenario as before, you can use Hamcrest to validate the list of strings as follows:

List<String> languages = Arrays.asList("Java", "Python", "C++");

assertThat(languages, hasSize(3));
assertThat(languages, hasItem("Java"));
assertThat(languages, not(hasItem("Ruby")));

Ease of Use With IDEs

When it comes to integration with IDEs (Integrated Development Environments), both Hamcrest and AssertJ provide a user-friendly experience, but there are some differences in how they operate that may influence your choice.


Hamcrest requires you to static import individual assertions, which means you need to know the name of the specific assertion you want to use. This can sometimes make it less convenient, especially if you are unfamiliar with all the available assertions.

Example of using Hamcrest with static import:

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.*;
import static org.junit.jupiter.api.Assertions.assertEquals;

List<String> languages = Arrays.asList("Java", "Python", "C++");

// Hamcrest assertion
assertThat(languages, hasSize(3));

// JUnit 5 assertion
assertEquals(3, languages.size());

// Additional Hamcrest example
assertThat(languages, contains("Java", "Python", "C++"));

Note that the Hamcrest version of assertThat(arg1, arg2) is not designed to be fluent like the AssertJ or other testing libraries, which may affect the readability and ease of chaining multiple assertions together.


On the other hand, AssertJ simplifies this process by requiring you to only static import the Assertions class. Once you’ve done this, you can use the assertThat(actual) method, and the IDE will automatically trigger the available methods when you type a period. This autocompletion feature makes it easier to discover and use the various assertions provided by AssertJ.

Example of using AssertJ with static import:

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

List<String> languages = Arrays.asList("Java", "Python", "C++");

Comparison of Assertion Failure Messages

When a test fails, the output of the assertion failure message is crucial for quickly identifying the cause of the failure. Here, we will compare the output of an assertion failure message in both Hamcrest and AssertJ.


Hamcrest provides clear and concise failure messages that describe what was expected and what was actually received. However, some developers find that these messages can sometimes be a bit limited in detail.

Example of a Hamcrest assertion failure message:

Expected: is <3>
     but: was <2>


AssertJ, on the other hand, is known for providing detailed and informative failure messages that help to quickly pinpoint the cause of a failed test.

Example of an AssertJ assertion failure message:

to be equal to:
but was not.

As seen from the examples above, both Hamcrest and AssertJ provide clear failure messages, but AssertJ tends to offer more detailed and helpful information. This detailed output can be particularly beneficial when debugging complex tests with multiple assertions, as it can help you quickly understand what went wrong and where to look to fix the issue.

Customizing Error Messages in Assertions

An important aspect to consider when choosing an assertion framework is the ability to customize error messages, and whether the framework supports string substitutions within these messages. Custom error messages are crucial as they provide clear and specific feedback when a test fails, making it easier to understand the context and cause of the failure.


AssertJ shines in this aspect as it allows you to provide custom error messages for each assertion, and it supports string substitutions, making your error messages more informative and tailored to your specific test cases.

Example of AssertJ custom error message with string substitution:

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

public class CustomErrorMessageTest {
  public void testName() {
    String name = "Alice";
      .overridingErrorMessage("Expected name to be Bob, but was %s", name)

In this example, if the test fails, it will display the message “Expected name to be Bob, but was Alice”.


Hamcrest also allows for custom error messages, but it doesn’t directly support string substitutions in the same way that AssertJ does.

Example of Hamcrest custom error message:

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

public class CustomErrorMessageTest {
  public void testName() {
    String name = "Alice";
    assertThat("Expected name to be Bob", name, equalTo("Bob"));

In this case, if the test fails, it will display the message “Expected name to be Bob”.

To sum up, both AssertJ and Hamcrest allow for custom error messages, but AssertJ takes it a step further by also supporting string substitutions within these messages, offering a more flexible and powerful way to communicate the context of test failures.

Writing Custom Assertions

The ability to write custom assertions is a powerful feature that allows developers to create more expressive and domain-specific tests. Both Hamcrest and AssertJ offer this capability, but there are some differences in their approach and ease of implementation.


In Hamcrest, custom assertions are created by implementing a matcher class. This allows you to define the specific behavior and failure message for your assertion. However, this process can sometimes be more involved and require more boilerplate code compared to AssertJ.

Example of a custom Hamcrest assertion:

import org.hamcrest.Description;
import org.hamcrest.TypeSafeMatcher;

public class IsEven extends TypeSafeMatcher<Integer> {
  protected boolean matchesSafely(Integer number) {
    return number % 2 == 0;

  public void describeTo(Description description) {
    description.appendText("an even number");

Usage of custom Hamcrest assertion:

import static org.hamcrest.MatcherAssert.assertThat;
import static org.example.IsEven.isEven;

public class CustomAssertionTest {
  public void testIsEven() {
    assertThat(4, isEven());


AssertJ takes a slightly different approach to custom assertions by providing a fluent API that makes it easier to chain together multiple conditions. This results in less boilerplate code and more readable tests.

Example of a custom AssertJ assertion:

import org.assertj.core.api.AbstractIntegerAssert;

public class IntegerAssert extends AbstractIntegerAssert<IntegerAssert, Integer> {
  public IntegerAssert(Integer actual) {
    super(actual, IntegerAssert.class);

  public IntegerAssert isEven() {
    if (actual % 2 != 0) {
      failWithMessage("Expected an even number but was <%s>", actual);
    return this;

Usage of custom AssertJ assertion:

import static org.example.IntegerAssert.assertThat;

public class CustomAssertionTest {
  public void testIsEven() {

In conclusion, while both Hamcrest and AssertJ provide the ability to create custom assertions, AssertJ tends to offer a more straightforward and flexible approach that can lead to more readable and maintainable tests.

In conclusion, while both frameworks are designed to be user-friendly and integrate well with IDEs, AssertJ has a slight edge in terms of ease of use due to its simpler static import process and the helpful autocompletion feature that assists developers in finding the right assertions for their tests.

AssertJ vs Hamcrest: Which to Choose?

The choice between AssertJ and Hamcrest largely depends on personal preference and the specific requirements of your project. Here are some crucial differences that could help guide your decision:

  1. Fluent API
    • AssertJ offers a fluent and chainable API, frequently resulting in test cases that are more concise and readable.
  2. Custom Assertions
    • Both AssertJ and Hamcrest provide the functionality to create custom assertions. However, AssertJ typically has a more straightforward approach, which often means less boilerplate code.
  3. Matcher Objects
    • Hamcrest is praised for its expressive matcher objects, which enhance the readability of assertions. Hamcrest’s expressive language helps in writing tests that read more like natural language, which can be particularly beneficial when working in a team or when you need to share your test results with non-technical stakeholders.
  4. Error Messages
    • AssertJ is reputed for producing detailed error messages, aiding significantly in debugging failed tests.
  5. String Substitutions in Error Messages
    • AssertJ supports string substitutions in custom error messages, adding an extra layer of flexibility and clarity when communicating test failures.

Each framework has its own strengths and weaknesses, and the best choice depends on your specific needs and preferences.

Ultimately, the decision of which assertion framework to choose—be it AssertJ or Hamcrest—rests in the hands of the development team. It is important for the team to carefully evaluate the specific needs of their project, the familiarity of team members with the framework, and the workflow that they are comfortable with.

Each framework has its own unique features and benefits, and what works for one team might not necessarily be the best fit for another. Therefore, it is crucial for teams to weigh the pros and cons, experiment with both options if possible, and then make an informed decision that aligns with their project requirements and team dynamics.

In Conclusion

Both AssertJ and Hamcrest are exceptional Java assertion frameworks that serve to improve the readability and quality of your test cases, albeit in different ways. AssertJ stands out with its fluent API and the flexibility it offers in creating custom assertions, while Hamcrest shines with its expressive matcher objects and extensive range of predefined matchers. The decision to choose one over the other ultimately lies with the development team, taking into consideration their project requirements, workflow, and personal preferences. Each framework has its own merits and can significantly enhance the testing experience when utilized effectively.

Related Articles:

Java • int vs long Post Date: 07 Dec 2023
In Java programming, understanding data types is crucial for efficient and error-free coding. Two fundamental data types often encountered are int and long. This article delves into their differences, use cases, and how they impact Java applications. By comprehending the nuances between these types, developers can make informed decisions, optimizing their code for performance and precision.
Java • Custom Annotations In Action Post Date: 06 Dec 2023
In the dynamic landscape of Java programming, custom annotations have become a pivotal tool, revolutionizing code development and maintenance. As specialized metadata, custom annotations in Java empower developers to infuse additional information into their code, enhancing readability, maintainability, and functionality. They simplify complex tasks like serialization and data validation, and improve communication in collaborative coding environments.
Functional Programming with Java Post Date: 03 Dec 2023
Functional Programming (FP) in Java marks a significant shift towards a more efficient and clean coding paradigm, integrating core principles like immutability, pure functions, and higher-order functions into its traditional object-oriented framework. This article delves into the pivotal role of lambda expressions and the Stream API in enhancing code readability and performance.
Java • Understanding the Command Design Pattern Post Date: 03 Dec 2023
The Command Design Pattern is a foundational concept in software engineering, offering a robust framework for encapsulating a request as an object. This article provides an insightful exploration into its mechanics, advantages, and real-world uses. By understanding this pattern, developers can enhance the flexibility, maintainability, and scalability of their software projects.
Java • Deep Dive into the Visitor Design Pattern Post Date: 02 Dec 2023
This article takes a deep dive into the Visitor Design Pattern, a key concept in software engineering for efficient problem-solving. We’ll define the pattern and its place in design patterns, focusing on its core components: the Visitor and Element interfaces. The discussion extends to real-world applications, demonstrating its versatility across different programming languages.
Java vs. C# Post Date: 29 Nov 2023
In the dynamic and ever-evolving world of software development, Java and C# stand as two titans, each with its own unique strengths, philosophies, and ecosystems. This article delves into an in-depth comparison of Java and C#, exploring their historical context, language features, performance metrics, cross-platform capabilities, and much more.
Java • Mockito vs EasyMock Post Date: 26 Nov 2023
Java, a widely-used programming language, has evolved significantly over the years, especially in the realm of testing. In this digital era, where software development is fast-paced and highly iterative, the importance of efficient and reliable testing frameworks cannot be overstated. Among the various tools and libraries available for Java developers, Mockito and EasyMock stand out as popular choices for unit testing.
Java • Single Responsibility Principle Post Date: 23 Nov 2023
The Single Responsibility Principle (SRP), a fundamental concept within the SOLID principles, is crucial in Java programming. It dictates that each class should have only one reason to change, focusing on a single functionality or concern. This approach is particularly effective in Java, known for its robust object-oriented features, where SRP enhances maintainability, readability, and scalability of applications.
Java • Are Static Classes Things Of The Past? Post Date: 22 Nov 2023
Static classes have been a staple in the programming world for decades. Traditionally, a static class is one where all members and functions are static, meaning they belong to the class itself rather than any specific instance of the class. This makes static classes an efficient tool for grouping related functions and data that do not require object instantiation to be accessed.
Java • Multiple Inheritance Using Interface Post Date: 22 Nov 2023
Amongst the many facets of object-oriented programming, the concept of inheritance is fundamental. Multiple inheritance, a feature where a class can inherit from more than one superclass, can be particularly powerful but also complex. Java, however, does not support multiple inheritance directly in the way languages like C++ do. Instead, it offers a robust alternative through interfaces.
Java • Interfaces Are Replacing Abstract Classes Post Date: 22 Nov 2023
The Java programming language, renowned for its robust structure and versatile capabilities, has witnessed a notable evolution in its fundamental components over the years. Among these, the role and functionality of interfaces and abstract classes have undergone significant changes, particularly with the introduction of new features in Java 8.
Java • Decoupling Arbitrary Objects Through Composition Post Date: 22 Nov 2023
In the dynamic landscape of software development, the concept of object decoupling plays a pivotal role in crafting efficient, maintainable, and scalable applications. At its core, object decoupling refers to the design approach where components of a program are separated in such a manner that they are independent, yet functionally complete. This separation ensures that changes in one part of the system minimally impact other parts, facilitating easier updates, debugging, and enhancement.
Java Primitives & Primitive Wrappers Post Date: 16 Nov 2023
Java, a robust and widely-used programming language, stands out for its efficient handling of data types. Central to its functionality are the Java primitives and their corresponding wrapper classes. This article delves into the essence of Java primitives, their types, and the distinction between primitive and non-primitive data types, including examples to illustrate these concepts.
Java • Primitive int vs Integer Best Practices Post Date: 07 Nov 2023
In Java, one of the foundational decisions developers must make pertains to choosing between primitive types and their corresponding wrapper classes, such as int and Integer. Both have their place in Java applications, and understanding their differences is paramount for writing efficient and effective code.
Java • Harnessing Static and Default Methods in Interfaces Post Date: 06 Nov 2023
The arrival of static and default methods in Java 8 marked a significant shift in interface capabilities, expanding their functionality and versatility in Java’s object-oriented ecosystem. This article explores the nuances of these features and their impacts on Java programming, simplifying complex concepts and illustrating their practical applications in modern software development.
Java Modern Collection Utilities Post Date: 06 Nov 2023
Java’s evolution has always been about simplifying complexity and enhancing efficiency. The collection utilities have undergone significant improvements since JDK 8, transitioning from the Collections utility class to the intuitive List.of(), Map.of(), and Set.of() methods.
Java • Concatenating Streams Post Date: 06 Nov 2023
Merging or combining multiple data sequences into a single stream is a common task in Java programming, especially when working with the robust Stream API introduced in Java 8. Understanding how to effectively concatenate streams can greatly simplify your data processing tasks.
Java • Unit Testing Best Practices Post Date: 26 Oct 2023
Unit testing is a fundamental aspect of software development, ensuring that each individual unit of source code is thoroughly examined and validated for correctness. With Java being one of the most widely used programming languages, it is crucial to adhere to the best practices for unit testing in Java to maintain the integrity and performance of the software.
Factory Design Pattern Best Practices Post Date: 23 Oct 2023
The Factory Pattern is a creational design pattern that provides an interface for creating objects in a superclass but allows subclasses to alter the type of objects that will be created. By following best practices in the implementation of the Factory Pattern, developers can achieve loose coupling, improved maintainability, and enhanced flexibility in their code.
Logback for Beginners Post Date: 19 Oct 2023
Logback, a Java-based logging framework within the SLF4J (Simple Logging Facade for Java) ecosystem, is the preferred choice in the Java community, serving as an enhanced successor to the popular Log4j project. It not only carries forward the legacy of Log4j but also brings to the table a quicker implementation, more comprehensive configuration options, and enhanced flexibility for archiving old log files.
Java Parallel Streams Post Date: 19 Oct 2023
Java, one of the most versatile and widely-used programming languages, has continuously evolved to adapt to the demands of modern application development. With the advent of parallel streams in Java 8, developers have been endowed with a robust tool to optimize performance and bolster efficiency in their applications.
Java • Modern Looping And Filtering with Stream API Post Date: 19 Oct 2023
Java has constantly evolved since its inception, presenting developers with numerous tools and methods to make coding more efficient and readable. Among these are modern techniques for looping and filtering data.
Java • Converting Strings To List Post Date: 19 Oct 2023
When it comes to working with Java, converting strings into lists is a common and essential operation that can significantly enhance your data processing capabilities. Whether you’re a seasoned programmer or just starting, mastering this technique will prove to be invaluable in your coding endeavors.
Observer Design Pattern Post Date: 18 Oct 2023
In the vast realm of software architecture, design patterns serve as the foundational blueprints that enable the creation of flexible, robust, and efficient systems. Among these, the Observer Design Pattern is a beacon, renowned for its ability to adeptly manage changes and relay updates.
Factory Design Pattern Post Date: 18 Oct 2023
Design patterns act as blueprints or templates for designing software solutions. The Factory Design Pattern is a creational pattern focused on object creation. This pattern, a crucial piece of the design structure, provides a guide for developers to create objects without specifying the exact class of the object that will be created.
Java var Best Practices Post Date: 18 Oct 2023
Java, with each release and update, continually evolves to simplify the developer’s journey while preserving its core tenets of readability and robustness. One of the notable introductions in Java 10 was the var keyword. As with most new features, it sparked debates and questions regarding its efficacy and best practices.
URI vs URL in Java Post Date: 16 Oct 2023
In the realm of Java and web development, the terms URL and URI often emerge in discussions, leaving some in a quagmire of confusion. This article aims to elucidate the disparities between the two, elucidating their syntax, utilization in Java, and the nuances that set them apart.
Java vs JavaScript • Which Is In More Demand? Post Date: 02 Oct 2023
Java and JavaScript, despite their similar names, serve distinct purposes within the realm of software development. As both languages continue to evolve and find niches in the modern tech landscape, it’s crucial to understand their differences and their respective market demands.
Java Cloning Strategies Post Date: 23 Jun 2023
Object copying is a fundamental aspect of Java programming, finding relevance and utility in diverse contexts. Whether it’s creating independent copies of objects, maintaining object state, or avoiding unintended side effects, understanding efficient and reliable cloning strategies is essential.
Java Comprehensive Guide Post Date: 17 May 2023
Java is a versatile programming language that has gained widespread popularity for its platform independence and robustness. In this comprehensive guide, we will delve into the various aspects of Java programming, covering essential concepts, tools, and best practices.
Java vs Kotlin Post Date: 16 May 2023
Java vs Kotlin: A Comprehensive Comparison Java and Kotlin are two popular programming languages that have gained significant traction in the software development industry. In this article, we will compare and contrast these languages, exploring their features, advantages, and use cases.
Java • Converting Strings To Map Post Date: 03 May 2023
This article discusses converting a string of key-value pairs that are delimited by a specific character, known as a delimiter, into a Map in Java.
Maven vs Gradle Post Date: 01 May 2023
Maven and Gradle are two of the most popular build automation tools for Java-based projects. Both tools are designed to simplify the build process, manage dependencies, and facilitate project organization.
Java 19 Virtual Threads Post Date: 04 Apr 2023
In this article, we will provide an overview of virtual threads in Java and their use in concurrent programming. We will define what virtual threads are and how they differ from normal threads. Additionally, we will discuss the benefits of virtual threads over traditional concurrency approaches and provide code examples to illustrate the differences between the two.
Decoupling Domain Objects: Simplifying System Architecture Post Date: 31 Mar 2023
When you design an object-oriented system from top to bottom, sometimes the objects that represent the “domain” (what the system is about) don’t match the objects that represent the “entities” (what the system stores). To solve this problem, you can use a technique called “decoupling” to separate the layers of objects.
Java Final Modifier Post Date: 27 Mar 2023
In Java, the final keyword (also known as a modifier) is used to mark a variable, method, or class as immutable, meaning its value or behavior cannot be modified once it has been initialized.
Java Records Post Date: 14 Mar 2023
A Java record is a new feature introduced in Java 14 that allows developers to create a class that is primarily used to store data. A record is essentially a concise way to define a class that consists mainly of state (fields) and accessors (getters).
Java 17 Features Post Date: 14 Mar 2023
JDK 17, introduces several new features and improvements, including enhanced random number generators, new encoding-specific methods for the String class, and default classes for Java ciphers. It also removes the experimental AOT and JIT compilers, and introduces support for Sealed Classes and Records. These changes provide developers with more flexibility and control, making it easier to write efficient and secure Java applications.
Java Optional - Why Developers Prefer Optional Values Post Date: 12 May 2019
This article discusses the use of Java Optional to introduce optional values instead of null. We will deep dive into understanding why developers prefer the Optional class to clearly communicate an optional value as opposed to a vague null representation of a variable.
Java • Int to String Conversion Guide Post Date: 11 May 2019
In Java, often times the ability to return a string representing the specified integer is a common task. This article illustrates several mechanisms to convert int to a string in Java. In the opposite scenario, the means to resolve an integer representing the value of the specified String. The returned value is an Integer object that is the equivalent integer value of the argument string.
Java • Double to String Conversion | Beginner's Guide Post Date: 11 May 2019
Converting double to a String value in Java has been a typical task to do for software development. This article discusses the various ways on how to convert a double to a string in Java. While there are advantages in representing a double to its String object representation, the opposite task of converting a String object to a double can also be addressed. This document examines the reasons why conversions of double in Java are beneficial for beginners who are learning to develop in java.
Setting Java Compiler Version in Maven Post Date: 27 Aug 2018
This document demonstrates ways to set the java compiler version in maven via the maven.compiler.target property and the maven-compiler-plugin configuration section.
Getting Started with Maven Build System in Java Projects Post Date: 16 Aug 2018
The following page will illustrate how to get started with the maven build system in your java projects.  Use this guide as a reference when using Maven for the very first time.
Getting Started With Java Post Date: 15 Aug 2018
The following page will illustrate how to get started with the Java Programming Language.  In addition, this document provides an overview of how to install java and the environment variables you will need to set.  A hands-on approach illustrates how to compile and run your first Hello World java code.
Getting Started With Gradle Post Date: 14 Aug 2018
The following page will be an excellent guide with getting started with the gradle build system in your Java™ projects.  Use this guide as a reference when using Gradle as a build system for the very first time.