This book is about the techniques of using tests to guide the development of object-oriented software, not about specific technologies. To demonstrate the techniques in action, however, we've had to pick some technologies for our example code. For the rest of the book we're going to use Java, with the JUnit 4 and jMock 2 testing frameworks. If you're using something else, we hope that we've been clear enough so that you can apply these ideas in your environment.

In this chapter we briefly describe the programming interfaces for these two frameworks, just enough to help you make sense of the code examples we've written. If you already know how to use them, then you can skip this chapter.

We use JUnit 4 as our Java test harness. It's small, open-source, bundled with many IDEs and can be downloaded from www.junit.org if your IDE does not include it. The essence of JUnit is that it uses reflection to walk the structure of a class and run whatever it can find in that class that represents a test. That sentence will make more sense if we show an example, here's a test that exercises a Catalog class that manages a collection of Entries:

public class CatalogTest {
  final Catalog catalog = new Catalog();
  
  @Test public void containsAnAddedEntry() { 
    Entry entry = new Entry("fish", "chips");
    catalog.add(entry);
    assertTrue(catalog.contains(entry));
  }
  
  @Test public void indexesEntriesByName() {
    Entry entry = new Entry("fish", "chips");
    catalog.add(entry);
    
    assertEquals(entry, catalog.entryFor("fish"));  
    assertNull(catalog.entryFor("missing name"));  
  }
}

@Test(expected=IllegalArgumentException.class)
public void cannotAddTwoEntriesWithTheSameName() {
  catalog.add(new Entry("fish", "chips");
  catalog.add(new Entry("fish", "tartare sauce");
}

public class CatalogTest {
  final Catalog catalog = new Catalog();
  final Entry entry = new Entry("fish", "chips");

  @Before public void fillTheCatalog() {
    catalog.add(entry);
  }
  
  @Test public void containsAnAddedEntry() {
    assertTrue(catalog.contains(entry));
  }
  
  @Test public void indexesEntriesByName() {
    assertEquals(equalTo(entry), catalog.entryFor("fish"));  
    assertNull(catalog.entryFor("missing name"));  
  }

  @Test(expected=IllegalArgumentException.class)
  public void cannotAddTwoEntriesWithTheSameName() {
    catalog.add(new Entry("fish", "tartare sauce");
  }
}

Hamcrest is a framework for writing declarative match criteria. While not a testing framework itself, Hamcrest is used by several testing frameworks, including JUnit, jMock and Window Licker, which we use in the worked example for end-to-end testing.

A Hamcrest Matcher reports whether an object matches some criteria and can describe its criteria. For example, this code creates Matchers that matche if given strings that contain a given substring, and uses them to make some assertions.

String s = "yes we have no bananas today";

Matcher<String> containsBananas = new StringContains("bananas");
Matcher<String> containsMangos = new StringContains("mangos");

assertTrue(containsBananas.matches(s));
assertFalse(containsMangos.matches(s));

Matchers are not usually instantiated directly. Instead, Hamcrest provides static factory methods for all of its matchers to make code that creates matchers more readable. For example

assertTrue(containsString("bananas").matches(s));
assertFalse(containsString("mangos").matches(s));

In practice, however, we use Matchers in combination with JUnit's assertThat, which uses the Matcher's self-describing structure when an assertion fails to generate a message that makes it clear exactly what went wrong. We can rewrite the assertions as:

assertThat(s, containsString("bananas"));
assertThat(s, not(containsString("mangos"));

The second assertion demonstrates one of Hamcrest's most useful features: defining new criteria by combining existing matchers. The not method is a factory function that creates a matcher that reverses the sense of any matcher passed to it. Matchers are designed so that when they're combined, both the code and the failure messages are self-explanatory. For example, if we change the second assertion to fail:

assertThat(s, not(containsString("bananas"));

the failure report is:

java.lang.AssertionError: 
Expected: not a string containing "bananas"
     got: "Yes, we have no bananas"

This feature makes assertThat a convenient alternative to writing new assertion methods. Instead of writing code to explicitly check a condition and generate informative error messages, we can pass a matcher expression to assertThat and let it do the work.

Hamcrest is also user extensible. If we need to check a specific condition, we can write a new matcher, by implementing the Matcher interface and an appropriately-named factory method, and the result will combine seamlessly with the existing matcher expressions.

jMock 2 plugs into JUnit (and other test frameworks) with support for the Mock Objects testing style introduced in Chapter 2, Test-Driven Development with Objects. jMock creates mock objects dynamically, so you don't have to write your own implementations of the types you want to mock. It also provides a high-level API for specifying how the object test should invoke the mock objects it interacts with, and how the mock objects will behave in response.

The core concepts of the jMock API are the Mockery, Mock Objects and Expectations. The Mockery represents the context of the object under test, its neighbouring objects; Mock Objects stand in for the real neighbours of the object under test while the test runs; and, Expectations describe how the object under test should invoke its neighbours during the test.

Again, let's start with an example to show how these fit together. The test below asserts that a AuctionMessageTranslator will parse a given message text to generate an auctionClosed() event—for now just concentrate on the structure, the test will turn up again in context in Chapter 8, Getting ready to bid.

@RunWith(jMock.class) 
public class AuctionMessageTranslatorTest {
  private final Mockery context = new JUnit4Mockery(); 

  private final AuctionEventListener listener =  
                              context.mock(AuctionEventListener.class); 

  private final AuctionMessageTranslator translator = 
                                new AuctionMessageTranslator(listener); 

  @Test public void
  notfiesAuctionClosedWhenCloseMessageReceived() {
    Message message = new Message();
    message.setBody("SOLVersion: 1.1; Event: CLOSE;"); 
    
    context.checking(new Expectations() {{ 
      exactly(1).of (listener).auctionClosed(); 
    }});
  
    translator.processMessage(UNUSED_CHAT, message); 
    
  }
}

oneOf(o).doSomething(with(any(String.class)); will(returnValue(20));