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.
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.5.0</version>
<scope>test</scope>
</dependency>Hamcrest Compose provides the following matchers:
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")));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. If the function is a method reference then the method name will be used for the description instead. To override this a feature description can be specified:
assertThat(person, hasFeature("a person with first name", Person::getFirstName, equalTo("ham")));When using lambdas the toString is not particularly informative so a feature description can also be specified:
assertThat(person, hasFeature("a person with first name", p -> p.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", p -> p.getFirstName(), equalTo("ham")));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.
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.
Prerequisites:
- Configure GPG key pair
- Configure Maven master password
- Configure Maven settings for server
sonatype-nexus-stagingwith your encrypted OSSRH credentials
To release a new version:
mvn release:clean release:preparemvn release:perform -DuseReleaseProfile- Enter GPG passphrase when prompted
