Hamcrest Compose

This library provides Hamcrest matchers to easily build composite matchers for objects. For example:

public static Matcher<Person> personEqualTo(Person expected) {
    return compose("a person with", hasFeature("title", Person::getTitle, equalTo(expected.getTitle())))
        .and(hasFeature("first name", Person::getFirstName, equalTo(expected.getFirstName())))
        .and(hasFeature("last name", Person::getLastName, equalTo(expected.getLastName())));
}

See the demo module to run this example. The PersonMatchersTest test case defines the behaviour of this matcher.

Getting started

Hamcrest Compose is available in the Maven Central repository. Start by adding a dependency to your Maven project:

<dependency>
    <groupId>org.hobsoft.hamcrest</groupId>
    <artifactId>hamcrest-compose</artifactId>
    <version>0.4.0</version>
    <scope>test</scope>
</dependency>

Usage

Hamcrest Compose provides the following matchers:

ComposeMatchers.compose

This factory method builds a composite matcher that logically ANDs a number of other matchers. For example:

assertThat("ham", compose(startsWith("h")).and(containsString("a")).and(endsWith("m")));

This differs from Hamcrest's composite matchers allOf and both in the following ways:

It does not short circuit. This means that all mismatches are reported, not just the first one.
It does not describe itself using parenthesis. This produces more readable descriptions.
It describes each matcher on a separate line
It supports an optional description to help describe the composition
It does not repeat the matcher's description when describing a mismatch

It can also be built from a list or an array of matchers when a fluent style is inconvenient:

assertThat("ham", compose(asList(startsWith("h"), containsString("a"), endsWith("m"))));
assertThat("ham", compose(startsWith("h"), containsString("a"), endsWith("m")));

ComposeMatchers.hasFeature

This factory method builds a matcher that matches a 'feature' of an object. A feature is any value that can be obtained from the object by a Function. Typically this is a lambda such as a method reference, for example:

assertThat(person, hasFeature(Person::getFirstName, equalTo("ham")));

By default this matcher will describe itself and any mismatches by using the toString method of the feature function. When using lambdas this is not particularly informative so a feature description can be specified:

assertThat(person, hasFeature("a person with first name", Person::getFirstName, equalTo("ham")));

This feature description is also used to describe any mismatches. To specify a feature name for the mismatch only:

assertThat(person, hasFeature("a person with first name", "first name", Person::getFirstName, equalTo("ham")));

ComposeMatchers.hasFeatureValue

This factory method builds a matcher that matches a feature value of an object. For example:

assertThat(person, hasFeatureValue(Person::getFirstName, "ham"));

It is a convenience method for hasFeature with an equalTo matcher.

Using with Mockito

When using Mockito the hasFeature matcher can provide an alternative to ArgumentCaptor. Consider their example:

ArgumentCaptor<Person> argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());

We can replace ArgumentCaptor with a custom argument matcher that uses hasFeature:

verify(mock).doSomething(argThat(hasFeature(Person::getName, equalTo("John"))));

The downside to this approach is that Mockito does not use the matcher to describe any mismatches. Instead it simply writes the actual argument using toString which makes diagnosing the mismatch harder.

License

Apache License 2.0