Spotify Hamcrest

This is a collection of libraries extending the Hamcrest matching library with useful matchers. We consider this library in beta but use it in many of our internal projects.

• Spotify Hamcrest
  • Download
  • Getting Started
    • POJO matchers
    • JSON matchers
    • java.util.Optional matchers
    • Future matchers
      • raw Future matchers
      • Java 8's CompletableFuture matchers
  • Prerequisities
  • Releasing
  • Code of conduct
  • Ownership

Download

Each of these modules is published to Maven Central with the groupId of com.spotify. The list of modules available is:

• hamcrest-pojo
• hamcrest-jackson
• hamcrest-optional
• hamcrest-future

Getting Started

POJO matchers

Many applications at Spotify are very data heavy. They might be aggregation services that combine a lot of data structures into even more complicated data structures. And the basic data structures are usually complicated to begin with.

The POJO matcher library lets you describe the structure of a POJO in a fluent style and then match against that structure. It's optimized for very complicated objects with a lot of properties. When a mismatch occurs, the library tries to minimally describe the mismatch.

Example:

final List<User> users;
try (Stream<User> userStream = sut.fetchAllUsers()) {
  users = userStream.collect(Collectors.toList());
}

assertThat(users, contains(
    pojo(User.class)
        .where("address", is(
            pojo(Address.class)
                .withProperty("street", is("Main Street"))
                .withProperty("country", is("US"))
        ))
        .where("product", is(
            pojo(Product.class)
                .withProperty("id", is(1))
                .withProperty("name", is("premium"))
                .withProperty("metadata", is("{\"foo\": [\"bar\", \"baz\"]}"))
                .withProperty("creationDate", is(Timestamp.from(Instant.EPOCH)))
                .withProperty("isTest", is(false))
        ))
));

Example output:

Expected:
iterable containing [User {
  address(): is Address {
    getStreet(): is "Main Street"
    getCountry(): is "US"
  }
  product(): is Product {
    getId(): is <1>
    getName(): is "premium"
    getMetadata(): is "{\"foo\": [\"bar\", \"baz\"]}"
    getCreationDate(): is <1970-01-01 01:00:00.0>
    getIsTest(): is <false>
  }
}]

but:
item 0: User {
  ...
  product(): Product {
    ...
    getMetadata(): was "{\"foo\": \"bar\"}"
    ...
  }
  ...
}

JSON matchers

Similar to the POJO matchers, the JSON matchers let you describe a JSON structure and match against it.

The match can be on a String or a jackson JsonNode.

// You can match a String
String jsonString = "{" +
 "  \"foo\": 1," +
 "  \"bar\": true," +
 "  \"baz\": {" +
 "    \"foo\": true" +
 "  }" +
 "}"

// You can match a Json String directly
assertThat("{}", isJsonStringMatching(jsonObject()));

// Or match a Jackson node
JsonNode json = new ObjectMapper().readTree(jsonString);
assertThat(json, is(
     jsonObject()
         .where("foo", is(jsonInt(1)))
         .where("bar", is(jsonBoolean(true)))
         .where("baz", is(
             jsonObject()
                 .where("foo", is(jsonNull()))))));

A failing test would look like:

Expected:
{
  "foo": is a number node is <1>
  "bar": is a boolean node is <false>
  "baz": is {
    "foo": is a null node
  }
}

but:
{
  ...
  "baz": {
    ...
    "foo": was not a null node, but a boolean node
    ...
  }
  ...
}

You can match a JSON Array by combining with existing Hamcrest collection Matchers:

String jsonArrayString = "["foo", "bar"]";
JsonNode json = new ObjectMapper().readTree(jsonArrayString);
assertThat(json, is(jsonArray(contains(jsonText("foo"), jsonText("bar")))));

java.util.Optional matchers

com.spotify:hamcrest-optional provides matchers for the Java 8 Optional type so you don't have to unpack the Optional in your tests.

final Optional<String> response = methodUnderTest();
assertThat(response, is(optionalWithValue(equalTo("foo")));

final Optional<Collection<Foo>> col = anotherMethod();
assertThat(response, is(optionalWithValue(containsInAnyOrder(...))));

// or if you only care that the Optional is non-empty:
assertThat(response, is(optionalWithValue()));

// or if you expect an empty Optional:
assertThat(response, is(emptyOptional()));

Future matchers

Similar to the Optional matchers, the CompletionStage / CompletableFuture matchers in com.spotify:hamcrest-future allow you to assert against the value or completion state of a CompletionStage without having to unpack it in your test code or handle the checked exceptions of Future.get() (or using Futures.getUnchecked(future)).

There are four dimensions you can choose from when using Future matchers:

• raw Future vs Java 8's CompletableFuture
• blocking vs non-blocking
  • blocking: the matcher will wait, perhaps indefinitely, for the future to complete
  • non-blocking: the matcher will not match if the future is not yet completed
• completed successfully vs completed with an exception
• match anything vs pass in another matcher

So there are a total of 16 methods you can call:

raw Future matchers

Use com.spotify.hamcrest.future.FutureMatchers:

	blocking	non-blocking
successful	futureWillCompleteWithValue[That]()	futureCompletedWithValue[That]()
exceptional	futureWillCompleteWithException[That]()	futureCompletedWithException[That]()

Java 8's CompletableFuture matchers

Use com.spotify.hamcrest.future.CompletableFutureMatchers:

	blocking	non-blocking
successful	stageWillCompleteWithValue[That]()	stageCompletedWithValue[That]()
exceptional	stageWillCompleteWithException[That]()	stageCompletedWithException[That]()

Note that to test that a CompletionStage completed with a certain value or exception use ..That(..).

CompletionStage<List<Foo>> f = someMethod();
assertThat(f, stageCompletedWithValueThat(contains(...));

CompletionStage<Foo> c = methodThatShouldFail();
assertThat(c, stageCompletedWithExceptionThat(isA(FooException.class)));

If you want the matcher to block until the CompletionStage is completed, use stageWillCompleteWithValueThat(..):

// warning: might block forever if the stage never completes!
CompletionStage<List<Foo>> f = someMethod();
assertThat(f, stageWillCompleteWithValueThat(is(equalTo(...)));

Be careful when using this matcher as it might block forever if the stage never completes! Consider restructuring your tests so that the completions returned from the method/class being tested are immediately completed (e.g. using MoreExecutors.directExecutor, etc).

Prerequisities

Any platform that has the following

• Java 8+
• Maven 3 (for compiling)

Releasing

This plugin is uploaded to Maven Central via the Maven release plugin. You'll need credentials for Spotify's Sonatype account in your ~/.m2/settings.xml as well as a GPG key to sign the artifacts.

mvn -Dgpg.keyname=<KEY-ID> release:prepare release:perform

Code of conduct

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

Ownership

The Weaver squad is currently owning this project internally. We are currently in the evaluating process of the ownership of this and other OSS Java libraries. The ownership takes into account ONLY security maintenance.

This repo is also co-owned by other people:

• mattnworb