The Artima Developer Community
Sponsored Link

Agile Buzz Forum
Flexible JUnit assertions with assertThat()

0 replies on 1 page.

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 0 replies on 1 page
Joe Walnes

Posts: 151
Nickname: jwalnes1
Registered: Aug, 2003

Joe Walnes, "The Developers' Coach" from ThoughtWorks
Flexible JUnit assertions with assertThat() Posted: May 13, 2005 3:10 PM
Reply to this message Reply

This post originated from an RSS feed registered with Agile Buzz by Joe Walnes.
Original Post: Flexible JUnit assertions with assertThat()
Feed Title: Joe's New Jelly
Feed URL:
Feed Description: The musings of a ThoughtWorker obsessed with Agile, XP, maintainability, Java, .NET, Ruby and OpenSource. Mmm'kay?
Latest Agile Buzz Posts
Latest Agile Buzz Posts by Joe Walnes
Latest Posts From Joe's New Jelly


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...

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")));

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:


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:

Expected: (a string containing "color" or a string containing "colour")
but got : hello world

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: ");
      message.append("\nbut got : ").append(something).append('\n');

Now ensure all your test cases extend this instead of junit.framework.TestCase and you're done.

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));

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.


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.

Read: Flexible JUnit assertions with assertThat()

Topic: Inertia rules in the development space Previous Topic   Next Topic Topic: Atom Support fixed

Sponsored Links


Copyright © 1996-2017 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us