Check if a List Contains Elements With Certain Properties in Hamcrest

1. Overview

When writing unit tests in Java, particularly with the JUnit framework, we often need to verify that elements within a list have specific properties.

Hamcrest, a widely used Matcher library, provides straightforward and expressive ways to perform these checks.

In this tutorial, we’ll explore how to check if a list contains elements with specific properties using JUnit and Hamcrest’s Matchers.

2. Setting up Hamcrest and Examples

Before we set up examples, let’s quickly add Hamcrest dependency to our pom.xml:

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

We can check the artifact’s latest version in Maven Central.

Now, let’s create a simple POJO class:

public class Developer {
    private String name;
    private int age;
    private String os;
    private List<String> languages;
 
    public Developer(String name, int age, String os, List<String> languages) {
        this.name = name;
        this.age = age;
        this.os = os;
        this.languages = languages;
    }
    // ... getters are omitted
}

As the code shows, the Developer class holds some properties to describe a developer, such as name, age, the operating system (os), and programming languages (languages) the developer mainly uses.

Next, let’s create a list of Developer instances:

private static final List<Developer> DEVELOPERS = List.of(
    new Developer("Kai", 28, "Linux", List.of("Kotlin", "Python")),
    new Developer("Liam", 26, "MacOS", List.of("Java", "C#")),
    new Developer("Kevin", 24, "MacOS", List.of("Python", "Go")),
    new Developer("Saajan", 22, "MacOS", List.of("Ruby", "Php", "Typescript")),
    new Developer("Eric", 27, "Linux", List.of("Java", "C"))
);

We’ll take the DEVELOPERS list as an example to address how to check whether elements contain specific properties using JUnit and Hamcrest.

3. Using hasItem() and hasProperty()

Hamcrest provides a rich set of convenient Matchers. We can use the hasProperty() Matcher in combination with the hasItem() Matcher:

assertThat(DEVELOPERS, hasItem(hasProperty("os", equalTo("Linux"))));

This example shows how to check if at least one element’s os is “Linux“. 

We can pass a different property name to hasProperty() to verify another property, for instance:

assertThat(DEVELOPERS, hasItem(hasProperty("name", is("Kai"))));

In the example above, we use is(), an alias for equalTo(), to check if the list has an element with name equal to “Kai”.

Of course, in addition to equalTo() and is(), we can use other Matchers in hasProperty() to verify elements’ properties in different ways:

assertThat(DEVELOPERS, hasItem(hasProperty("age", lessThan(28))));
assertThat(DEVELOPERS, hasItem(hasProperty("languages", hasItem("Go"))));

The assertion statements read like natural language, such as: “assertThat the DEVELOPERS list hasItem which hasProperty whose name is age and value is lessThan 28″.

4. The anyOf() and allOf() Matchers

hasProperty() is convenient for checking one single property. We can also check if elements in a list satisfy multiple properties by combining multiple hasProperty() calls using anyOf() and allOf(). 

If any Matcher inside anyOf() is matched, the whole anyOf() is satisfied. Next, let’s understand it through an example:

assertThat(DEVELOPERS, hasItem(
  anyOf(
      hasProperty("languages", hasItem("C")),
      hasProperty("os", is("Windows"))) // <-- No dev has the OS "Windows"
));

As the example shows, although no element in the DEVELOPERS list has os equal to “Windows”, the assertion passes since we have an element (“Eric”)’s languages containing “C“.

Therefore, anyOf() corresponds to “OR” logic: if there is any element whose languages contains “C” OR os is “Windows“.

Conversely, allOf() performs “AND” logic. Next, let’s see an example:

assertThat(DEVELOPERS, hasItem(
  allOf(
      hasProperty("languages", hasItem("C")),
      hasProperty("os", is("Linux")),
      hasProperty("age", greaterThan(25)))
));

In the test above, we check whether at least one element in DEVELOPERS simultaneously satisfies the three hasProperty() Matchers within allOf().

Since “Eric” ‘s properties pass the three hasProperty() Matcher checks, the test passes.

Next, let’s make some changes to the test:

assertThat(DEVELOPERS, not(hasItem( // <-- not() matcher
  allOf(
      hasProperty("languages", hasItem("C#")),
      hasProperty("os", is("Linux")),
      hasProperty("age", greaterThan(25)))
)));

This time, we don’t have a match since no element can pass all three hasProperty() Matchers.

5. Using JUnit’s assertTrue() and Stream.anyMatch()

Harmcrest offers handy ways to verify that elements within a list have specific properties. Alternatively, we can use the standard JUnit assertTrue() assertion and anyMatch() from Java Stream API to perform the same checks.

The anyMatch() method returns true if any element in the stream passes the check function. Next, let’s see some examples:

assertTrue(DEVELOPERS.stream().anyMatch(dev -> dev.getOs().equals("Linux")));
assertTrue(DEVELOPERS.stream().anyMatch(dev -> dev.getAge() < 28));
assertTrue(DEVELOPERS.stream().anyMatch(dev -> dev.getLanguages().contains("Go")));

It’s worth noting that when we use a lambda to examine an element’s properties, we can directly call getter methods to get their values. This can be easier than Hamcrest’s hasProperty() Matcher, which requires property names as literal Strings.

Of course, if it’s required, we can easily extend the lambda expression to do complex checks:

assertTrue(DEVELOPERS.stream().anyMatch(dev -> dev.getLanguages().contains("C") && dev.getOs().equals("Linux")));

The test above shows a lambda expression to check multiple properties of an element in the stream.

6. Conclusion

In this article, we’ve explored various ways to assert if a list contains elements with certain properties using JUnit and Hamcrest.

Whether working with simple properties or combining multiple conditions, Hamcrest provides a powerful toolkit for validating the properties of elements within collections. Furthermore, Hamcrest Matchers make our tests more readable and expressive, enhancing the clarity and maintainability of our test code.

Alternatively, we can perform this kind of check using JUnit assertTrue() and anyMatch() from Stream API.

As always, the complete source code for the examples is available over on GitHub.