hamcrest-bean-matchers

Posted on: 2019-10-08 2019-10-08
Tags: Hamcrest, Testing

Hamcrest Bean Matchers

1. Overview

Hamcrest is a library that provides methods, called matchers, to help
developers write simpler unit tests. There are plenty of matchers, you
can get started by reading about some of them
here.

In this article, we’ll explore beans matchers.

2. Setup

To get Hamcrest, we just need to add the following Maven dependency to
our pom.xml:

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>java-hamcrest</artifactId>
    <version>2.0.0.0</version>
    <scope>test</scope>
</dependency>

The latest Hamcrest version can be found on
Maven
Central.

3. Bean Matchers

Bean matchers are extremely useful to check conditions over POJOs,
something that is frequently required when writing most unit tests.

Before getting started, we’ll create a class that will help us through
the examples:

public class City {
    String name;
    String state;

    // standard constructor, getters and setters

}

Now that we’re all set, let’s see beans matchers in action!

3.1. hasProperty

This matcher is basically to check if certain bean contains a specific
property identified by the property’s name:

@Test
public void givenACity_whenHasProperty_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city, hasProperty("state"));
}

So, this test will pass because our City bean has a property named
state.

Following this idea, we can also test if a bean has certain property and
that property has certain value:

@Test
public void givenACity_whenHasPropertyWithValueEqualTo_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city, hasProperty("name", equalTo("San Francisco")));
}

As we can see, hasProperty is overloaded and can be used with a
second matcher to check a specific condition over a property.

So, we can also do this:

@Test
public void givenACity_whenHasPropertyWithValueEqualToIgnoringCase_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city, hasProperty("state", equalToIgnoringCase("ca")));
}

Useful, right? We can take this idea one step further with the matcher
that we’ll explore next.

3.2. samePropertyValuesAs

Sometimes when we have to do checks over a lot of properties of a bean,
it may be simpler to create a new bean with the desired values. Then,
we can check for equality between the tested bean and the new one. Of
course, Hamcrest provides a matcher for this situation:

@Test
public void givenACity_whenSamePropertyValuesAs_thenCorrect() {
    City city = new City("San Francisco", "CA");
    City city2 = new City("San Francisco", "CA");

    assertThat(city, samePropertyValuesAs(city2));
}

This results in fewer assertions and simpler code. Same way, we can test
the negative case:

@Test
public void givenACity_whenNotSamePropertyValuesAs_thenCorrect() {
    City city = new City("San Francisco", "CA");
    City city2 = new City("Los Angeles", "CA");

    assertThat(city, not(samePropertyValuesAs(city2)));
}

Next, well see a couple of util methods to inspect class properties.

3.3. getPropertyDescriptor

There’re scenarios when it may come in handy being able to explore a
class structure. Hamcrest provides some util methods to do so:

@Test
public void givenACity_whenGetPropertyDescriptor_thenCorrect() {
    City city = new City("San Francisco", "CA");
    PropertyDescriptor descriptor = getPropertyDescriptor("state", city);

    assertThat(descriptor
      .getReadMethod()
      .getName(), is(equalTo("getState")));
}

The object descriptor retrieves a lot of information about the
property state. In this case, we’ve extracted the getter’s name and
assert that it is equal to some expected value. Note that we can also
apply other text matchers.

Moving on, the last method we will explore is a more general case of
this same idea.

3.4. propertyDescriptorsFor

This method does basically the same as the one in the previous section,
but for all the properties of the bean. We also need to specify how
high we want to go in the class hierarchy:

@Test
public void givenACity_whenGetPropertyDescriptorsFor_thenCorrect() {
    City city = new City("San Francisco", "CA");
    PropertyDescriptor[] descriptors = propertyDescriptorsFor(
      city, Object.class);

    List<String> getters = Arrays.stream(descriptors)
      .map(x -> x.getReadMethod().getName())
      .collect(toList());

    assertThat(getters, containsInAnyOrder("getName", "getState"));
}

So, what we did here is: get all the property descriptors from the bean
city and stop at the Object level.

Then, we just used Java 8’s features to filter the getter methods.

Finally, we used collections matchers to check something over the
getters list. You can find more information about collections matchers
here.

4. Conclusion

Hamcrest matchers consist of a great set of tools to be used across
every project. They’re easy to learn and become extremely useful in
short time.

Beans matchers in particular, provide an effective way of making
assertions over POJOs, something that is frequently required when
writing unit tests.

To get the complete implementation of this examples, please refer to
the
GitHub project.

getdocs

3043