Ignoring Fields During Comparison Using AssertJ

1. Introduction

AssertJ provides methods for ignoring fields during comparison testing. These methods simplify tests by focusing only on the relevant parts of the objects. This is particularly useful when working with objects that contain fields with dynamic or irrelevant values.

In this article, we’ll look at various methods for ignoring fields within the AssertJ fluent API. We’ll start by setting the required dependency and providing a simple example of an Employee class. Then, we’ll explore various use cases for ignoring specific fields during object comparisons.

2. Maven Dependency and Example Setup

Let’s add the assertj-core dependency to our  pom.xml:

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

The assertj-core dependency provides methods such as ignoringFields () and ignoringExpectedNullFields() to ignore fields during comparison.

Notably, projects like Spring Boot already get AssertJ through spring-boot-starter-test. Hence, we don’t need to explicitly add the dependency.

Moving on, let’s define a simple Employee class with the following fields:

public class Employee {
    public Long id;
    public String name;
    public String department;
    public String workAddress;
    public Double netSalary;
    public Double grossSalary;
    // standard constructor, getter, setter
}

Using the AssertJ fluent API, we can ignore fields in the Employee class during testing.

3. Using ignoringFields()

First, let’s see how we can specify one or more fields to ignore when comparing actual and expected objects using the ignoringFields() method.

Let’s write a unit test that compares two Employee objects and use the ignoringFields() method to ignore certain fields:

@Test
public void givenEmployeesWithDifferentFields_whenComparingIgnoringSpecificFields_thenEmployeesAreEqual() {

    Employee employee1 = new Employee(1L, "John Doe", "Engineering", "456 Work Ave", 7500.0, 10000.0);
    Employee employee2 = new Employee(2L, "Alan Turing", "Engineering", "101 Work Ave", 8000.0, 11000.0);

    Assertions.assertThat(employee1)
      .usingRecursiveComparison()
      .ignoringFields("id", "name", "workAddress", "netSalary", "grossSalary")
      .isEqualTo(employee2);
}

Here, we ignore id, name, workAddress, grossSalary, and netSalary when comparing employee1 and employee2 objects. As a result, the assertion only compares the department field. This means the assertion passes even though the ignored fields have different values in the two objects.

4. Using ignoringFieldsMatchingRegexes() 

Furthermore, AssertJ provides the ignoringFieldsMatchingRegexes() method, which allows us to ignore fields based on regular expressions.

Let’s see the method in action by writing a unit test:

@Test
public void givenEmployeesWithDifferentSalaries_whenComparingIgnoringFieldsMatchingRegexes_thenEmployeesAreEqual() {

    Employee employee1 = new Employee(1L, "Jane Smith", "Marketing", "456 Work Ave", 7000.0, 9500.0);
    Employee employee2 = new Employee(2L, "Steve Jobs", "Marketing", "456 Work Ave", 7200.0, 9800.0);

    Assertions.assertThat(employee1)
      .usingRecursiveComparison()
      .ignoringFieldsMatchingRegexes(".*id", ".*name", ".*Salary")
      .isEqualTo(employee2);
}

In the code above, we define two Employee objects with the same department and work address but different values for the other fields. Then, we compare the two employees while ignoring fields whose names match the specified regular expressions. For instance, .*Salary matches the netSalary and grossSalary.

5. Using ignoringExpectedNullFields()

Moreover, let’s look into the ignoringExpectedNullFields() method in the AssertJ API. This method ignores fields that are null in the expected object during comparison. This is particularly useful when only some fields are significant in the expected object, and others aren’t set or are irrelevant.

Let’s suppose we want to compare two Employee objects, but in the expected object, some fields are null and should be ignored:

@Test
public void givenEmployeesWithNullExpectedFields_whenComparingIgnoringExpectedNullFields_thenEmployeesAreEqual() {
    Employee expectedEmployee = new Employee(null, "Alice Johnson", null, null, null, null);
    Employee actualEmployee = new Employee(3L, "Alice Johnson", "HR", "123 Work Ave", 6500.0, 9000.0);

    Assertions.assertThat(actualEmployee)
      .usingRecursiveComparison()
      .ignoringExpectedNullFields()
      .isEqualTo(expectedEmployee);
}

Here, the comparison only considers the non-null fields in the expectedEmployee object. As a result, the assertion compares the name field, while ignoring the id, department, workAddress, netSalary, and grossSalary fields.

6. Using usingRecursiveFieldByFieldElementComparatorIgnoringFields()

Finally, the usingRecursiveFieldByFieldElementComparatorIgnoringFields() method allows us to compare elements of a collection while ignoring specific fields. It recursively compares each element field by field, excluding the fields specified as method arguments.

Let’s demonstrate its usage by writing a unit test:

@Test
public void givenEmployees_whenComparingIgnoringFields_thenContainsEqualElements() {
    Employee actual1 = new Employee(1L, "John Doe", "Engineering", "456 Work Ave", 7500.0, 10500.0);
    Employee actual2 = new Employee(2L, "John Doe", "Engineering", "101 Work Ave", 8000.0, 12000.0);
    Employee expected1 = new Employee(3L, "John Doe", "Engineering", "Nil", 0.0, 0.0);
    Employee expected2 = new Employee(4L, "John Doe", "Engineering", "Nil", 0.0, 0.0);

    List<Employee> actual = List.of(actual1, actual2);
    List<Employee> expected = List.of(expected1, expected2);

    Assertions.assertThat(actual)
      .usingRecursiveFieldByFieldElementComparatorIgnoringFields(
        "id", "workAddress", "netSalary", "grossSalary")
      .containsExactlyInAnyOrderElementsOf(expected);
}

In the code above, we have a list of actual employees and a list of expected employees. We ignore the id, workAddress, grossSalary, and netSalary fields. Therefore, the assertion only considers the name and department fields when comparing the elements.

7. When to Use Any of the Methods

We can choose the appropriate method based on needs. In a scenario where we intend to exclude fields that may vary between objects but are irrelevant to the test, we can use the ignoringFields() method.

Then, we can use the ignoringFieldsMatchingRegexes() method when we want to ignore fields whose names match a regular expression. In a case where nulls are expected in an object, we can use the ignoringExpectedNullFields() method.

Finally, if we intend to compare elements in collections, we can use the .usingRecursiveFieldByFieldElementComparatorIgnoringFields() method.

8. Conclusion