Software development. And stuff.

The matcher API of Hamcrest is typically associated with assertThat() or mocks. I always knew other people would find good uses for it, but I never really knew what.

I particularly like these:

Collection processing

Håkan Råberg blogged about how Hamcrest can be used with iterators:

List<Integer> numbers = Arrays.asList(-1, 0, 1, 2);
List<Integer> positiveNumbers = detect(numbers, greaterThan(0)));

List<String> words = Arrays.asList("cheese", "lemon", "spoon");
List<String> wordsWithoutE = reject(words, containingString("e"));

Nothing rocket-sciencey about it. But simple and useful because it reduces boilerplate code and get to use the ever growing library of Hamcrest matchers.

On top of that, combining Hamcrest with a CGLib generated proxy, he has built a staticly typed query API:

List<Person> employees = ...;
List<Integer> allAges
= collect(from(employees).getAge());
List<Person> allBosses
= collect(from(employees).getDepartment().getBoss());
List<Person> allAccountants
= select(from(employees).getDepartment().getName(),
containingString("Accounts"));

This is nice alternative to a string based query language as you get your IDE completions, refactoring, compile time checking etc, without the noise of boilerplate code.

Web testing

Robert Chatley has taken some of the concepts of his LiFT framework and reimplemented them using Hamcrest and WebDriver for performing web testing.

public void testHasLotsOfLinks() {
goTo("http://some/url");
assertPresenceOf(greaterThan(15), links());
assertPresenceOf(atLeast(1), link().with(text(containingString("Sign in"))));

clickOn(link().with(text(containingString("Sign in"))));
assertPresenceOf(exactly(1), title().with(text(equalTo("Sign in page"))));
}

Now initially this seems a bit wordy and strange. Robert has designed this as a literate API. If you adjust the syntax highlighting of your API and make the Java keywords and syntax less visible, you get this:

goTo "http://some/url"
assertPresenceOf greaterThan 15 links
assertPresenceOf atLeast 1 link with text containingString "Sign in"

clickOn link with text containingString "Sign in"
assertPresenceOf exactly 1 title with text equalTo "Sign in page"

The motivation here is that the API usage is self documenting and could be useful to non-programmers. The flip-side to this is that it’s actually quite hard to write APIs like this and the usage can take quite a bit of getting used to.

Robert also introduced a Finder interface (the link() and title() methods return Finder implementations). This allows you to factor out your own UI specific components:

assertPresenceOf(atLeast(1), signInLink());
clickOn(signInLink());
assertPresenceOf(exactly(1),
blogLink().with(urlParameter("name", containingString("joe"))));

This is the bit I really like.

Allowing abstractions of components and matching rules to be combined in many different ways, so tests can check exactly what they need to, resulting in reduced less brittle tests that are easier to maintain.

Other uses

As I hear of other uses I’m listing them on the Hamcrest wiki.

When it goes bad

Of course, like any technology, it’s easy to get carried away.

Here’s an example of Hamcrest gone bad:

assertThat(myNumber, anyOf(equalTo(0), allOf(greaterThan(5), lessThan(10))));

I’m not a LISP programmer, so I find that really hard to understand. Just because we have an assertTHAT() method, we don’t have to use it all the time. In this case it’s much simpler to use plain old assertTRUE():

assertTrue("myNumber should be 0 or between 5 and 10",
myNumber == 0 || (myNumber > 5 && myNumber < 10));

Even though the non-Matcher version is longer (it could be shortened by leaving out the message and using a shorter variable name, but that would make it harder to understand), I find it much easier to understand.

But, what if you actually needed to use a matcher (e.g. for the web testing or collection processing examples above)?

One approach is you could use higher level matcher that are composed of other matchers:

matcher = anyOf(equalTo(0), allOf(greaterThan(5), lessThan(10)))
// simplifies to
matcher = anyOf(equalTo(0), between(5, 10))

Complete tangent: An alternative to between(5, 10) is between(5).and(10). The latter makes for more literate code, but is harder to implement – again a design tradeoff.

Another approach is to create a one-off anonymous matcher implementation:

matcher = new CustomMatcher() {
public boolean matchesSafely(Integer n) {
return n == 0 || (n > 5 && n < 10);
}
}

What are you doing with Hamcrest?

Updates:

1. JUnit 4.4 now comes with Hamcrest and assertThat().