Flexible JUnit assertions with assertThat()
Over time I’ve found I end up with a gazillion permutation of assertion methods in JUnit: assertEquals, assertNotEquals, assertStringContains, assertArraysEqual, assertInRange, assertIn, etc.
Here’s a nicer way. jMock contains a constraint library for specifying precise expectations on mocks that can be reused in your own assertion method (and that’s the last time I’m going to mention mocks today, I promise – despite the frequent references to the jMock library).
By making a simple JUnit assertion method that takes a Constraint, it provides a replacement for all the other assert methods.
I call mine assertThat() because I think it reads well. Combined with the jMock syntactic sugar, you can use it like this:
assertThat(something, eq("Hello"));
assertThat(something, eq(true));
assertThat(something, isA(Color.class));
assertThat(something, contains("World"));
assertThat(something, same(Food.CHEESE));
assertThat(something, NULL);
assertThat(something, NOT_NULL);
Okay, that’s nice but nothing radical. A bunch of assert methods have been replaced with different methods that return constraint objects. But there’s more…
h3. Combining constraints
Constraints can be chained making it possible to combine them in different permutations. For instance, for virtually every assertion I do, I usually find that I need to test the negative equivalent at some point:
assertThat(something, not(eq("Hello")));
assertThat(something, not(contains("Cheese")));
Or maybe combinations of assertions:
assertThat(something, or(contains("color"), contains("colour")));
h3. Readable failure messages
The previous example can be written using the vanilla JUnit assert methods like this:
assertTrue(something.indexOf("color") > -1 || something.indexOf("colour") > -1);
Fine, the constraint based one is easier to read. But the real beauty is the failure message.
The vanilla JUnit assert fails with:
junit.framework.AssertionFailedError:
Useless! Means you have to put an explicit error message in the assertion:
assertTrue(something.indexOf("color") > -1 || something.indexOf("colour") > -1,
"Expected a string containing 'color' or 'colour'");
But the jMock constraint objects are self describing. So with this assertion:
assertThat(something, or(contains("color"), contains("colour")));
I get this useful failure message, for free:
junit.framework.AssertionFailedError: Expected: (a string containing "color" or a string containing "colour") but got : hello world
h3. Implementing it
The simplest way is to grab jMock and create your own base test class that extends MockObjectTestCase. This brings in convenience methods for free (I’m still not talking about mocks, honest). If you don’t want to extend this class, you can easily reimplement these methods yourself – it’s no biggie.
import org.jmock.MockObjectTestCase;
import org.jmock.core.Constraint;
public abstract class MyTestCase extends MockObjectTestCase {
protected void assertThat(Object something, Constraint matches) {
if (!matches.eval(something)) {
StringBuffer message = new StringBuffer("nExpected: ");
matches.describeTo(message);
message.append("nbut got : ").append(something).append('n');
fail(message.toString());
}
}
}
Now ensure all your test cases extend this instead of junit.framework.TestCase and you’re done.
h4. Defining custom constraints
Creating new constraints is easy. Let’s say I want something like:
assertThat(something, between(10, 20));
To do that I need to create a method that returns a Constraint object, requiring two methods; eval() for performing the actual assertion, and describeTo() for the self describing error message. This is something that can live in the base test class.
public Constraint between(final int min, final int max) {
return new Constraint() {
public boolean eval(Object object) {
if (!object instanceof Integer) {
return false;
}
int value = ((Integer)object).intValue();
return value > min && value < max;
}
public StringBuffer describeTo(StringBuffer buffer) {
return buffer.append("an int between ").append(min).append(" and ").append(max);
}
}
}
This can be combined with other constraints and still generate decent failure messages.
assertThat(something, or(eq(50), between(10, 20));
junit.framework.AssertionFailedError: Expected: (50 or an int between 10 and 20) but got : 43
In practice I find I only need to create a few of these constraints as the different combinations gives me nearly everything I need.
More about this in the jMock documentation.
h4. Summary
Since using this one assert method I’ve found my tests to be much easier to understand because of lack of noise and I’ve spent a lot less time creating ‘yet another assertion’ method for specific cases. And in most cases I never need to write a custom failure message as the failures are self describing.
h4. Updates
- The matchers from jMock have been pulled out into a new project, Hamcrest.
- A follow up to this post shows some creative uses of matchers, and talks a bit about when you shouldn’t use them.
- JUnit 4.4 now comes with assertThat()!
