Paul Moser » JUnit

Improving Java unit test readability and maintainability

Paul — Tue, 11 Dec 2007 23:17:06 +0000

The last year has seen me working with Ruby rather than Java and I have really come to like the the way tests (or rather specs) are structured in RSpec and the general way BDD approaches tests (specs).

RSpec splits the behaviour of a class up into what happens in different contexts. An example probably explains things better, taking a trivial case of a stack (I'll get to Java in a minute but even if you don't know Ruby I think this code should be understandable):

PLAIN TEXT

RUBY:

require File.dirname(__FILE__) + "/stack"
context "A populated Stack" do
setup do
@stack = Stack.new
["a","b","c"].each { |x| @stack.push x }
end
specify "should add to the top when sent #push" do
@stack.push "d"
@stack.peek.should == "d"
end
specify "should return the top item when sent #peek" do
@stack.peek.should == "c"
end
specify "should NOT remove the top item when sent #peek" do
@stack.peek.should == "c"
@stack.peek.should == "c"
end
specify "should return the top item when sent #pop" do
@stack.pop.should == "c"
end
specify "should remove the top item when sent #pop" do
@stack.pop.should == "c"
@stack.pop.should == "b"
end
end
context "An empty stack" do
setup do
@stack = Stack.new
end
specify "should be empty" do
@stack.should be_empty
end
specify "should no longer be empty after #push" do
@stack.push "anything"
@stack.should_not be_empty
end
specify "should complain when sent #peek" do
lambda { @stack.peek }.should raise_error(StackUnderflowError)
end
specify "should complain when sent #pop" do
lambda { @stack.pop }.should raise_error(StackUnderflowError)
end
end
context "An almost empty stack (with one item)" do
setup do
@stack = Stack.new
@stack.push 3
end
specify "should not be empty" do
@stack.should_not be_empty
end
specify "should remain not empty after #peek" do
@stack.peek
@stack.should_not be_empty
end
specify "should become empty after #pop" do
@stack.pop
@stack.should be_empty
end
end

So a stack should behave in a particular way:

A populated Stack
- should add to the top when sent #push
- should return the top item when sent #peek
- should NOT remove the top item when sent #peek
- should return the top item when sent #pop
- should remove the top item when sent #pop

An empty stack
- should be empty
- should no longer be empty after #push
- should complain when sent #peek
- should complain when sent #pop

An almost empty stack (with one item)
- should not be empty
- should remain not empty after #peek
- should become empty after #pop

(incidentally the above is output generated from the spec tool, a bit like generating JavaDocs from Java code)

I think splitting the behaviour up into these different contexts greatly improves the readability and maintainability of both the tests themselves and the code under test. But how to do it in Java?

It's possible to use RSpec to test Java code because you can run RSpec using JRuby, however I'm not sure if it is wise to drive the development of code in one language with tests in a different language, Ruby and Java approach numerous things very differently.

Now it would be possible to have numerous JUnit test classes for a given class, each one for a different context but this has it's drawbacks, when you make a change to your class you'd need to run numerous test cases, which you could get around by having a master testcase with a suite method that includes all the others, but then you have to maintain the list of testcases in the suite() method and it's all too easy for the list to get out of sync with the actual test cases. JUnit 4 provides a solution, you can use the Enclosed runner. The code below is an equivalent example to the RSpec one in Java.

PLAIN TEXT

JAVA:

import static org.junit.Assert.assertThat;
import static org.hamcrest.CoreMatchers.is;
import java.util.EmptyStackException;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.Enclosed;
@RunWith(Enclosed.class)
public class TestStack {
public static class AnEmptyStack {
private Stack stack = null;
@Before
public void setupAnEmptyStack() {
stack = new Stack();
}
@Test
public void shouldBeEmpty() {
assertThat(stack.isEmpty(), is(false));
}
@Test(expected = EmptyStackException.class)
public void shouldComplainWhenPeeked() {
stack.peek();
}
@Test(expected = EmptyStackException.class)
public void shouldComplainWhenPoped() {
stack.pop();
}
@Test
public void shouldNotBeEmptyAfterItemIsPushedOntoIt() {
stack.push(new Object());
assertThat(stack.isEmpty(), is(false));
}
}
public static class AStackThatIsNeitherEmptyNorFull {
private Stack stack = null;
@Before
public void setupAStackWithThreeItems() {
stack = new Stack();
stack.push("one");
stack.push("two");
stack.push("three");
}
@Test
public void shouldAddToTheTopWhenSentAPush() {
stack.push("four");
assertThat(stack.peek(), is("four"));
}
@Test
public void shouldReturnTheTopItemWhenSentAPeek() {
assertThat(stack.peek(), is("three"));
}
@Test
public void shouldNotRemoveTheTopItemWhenSentAPeek() {
assertThat(stack.peek(), is("three"));
assertThat(stack.peek(), is("three"));
}
@Test
public void shouldReturnTheTopItemWhenSentAPop() {
assertThat(stack.peek(), is("three"));
}
@Test
public void shouldRemoveTheTopItemWhenSentAPop() {
assertThat(stack.pop(), is("three"));
assertThat(stack.peek(), is("two"));
}
}
public static class AStackThatContainsOnlyOneItem {
private Stack stack = null;
@Before
public void setupAStackWithOneItem() {
stack = new Stack();
stack.push("one");
}
@Test
public void shouldNotBeEmpty() {
assertThat(stack.isEmpty(), is(false));
}
@Test
public void shouldNotBeEmptyAfterAPeek() {
stack.peek();
assertThat(stack.isEmpty(), is(false));
}
@Test
public void shouldBeEmptyAfterAPop() {
stack.pop();
assertThat(stack.isEmpty(), is(true));
}
}
}

As an aside I've also used the new assertThat() method and Hamcrest matchers as you get significantly better error messages when your tests fail that way.

To get a plain test output you could probably write a XSLT stylesheet that parses the test report, the stylesheet Kerry produced for use with Junit 3.x tests maybe a good starting point, or write a custom formatter and specify that in your JUnit Ant task.

There are also the JBehave and JDave BDD frameworks for Java which would be worth looking at if you like the look of BDD.

Unit testing interface implementations

Paul — Sun, 25 Feb 2007 23:41:21 +0000

It's bugged me for a while about how best to go about unit testing classes that implement multiple interfaces where those interfaces are implemented by multiple classes or where a class extends another class and implements one or more interfaces.

What I want to avoid is in each test class implementing the the same set of tests for the behavior specified by the interface. That's not very DRY.

If your classes only implement a single interface then you can have a base class with the tests for the interface and then separate test classes derived from that for each class implementing the interface. The problem arises when your classes implement multiple interfaces - Java doesn't support multiple inheritance for classes so you can't have a base test case for each interface.

One answer with JUnit 4 is to use the parameterized test runner - I haven't thought about JUnit 3, if you're not using JUnit 4 because you're still using a JVM that doesn't support annotations JSE 6 is out now, catch up!

You need to have a test case for your interface and configure this to run with the parameterized runner. You also have a static factory method that provides the various implementations of the interface to be used in each test.

As an example, say the container I'm writing (I'm not really - I know there is Apache Geronimo, JBoss, Hivemind etc - this is just an example) supports services that it can start and stop, so I have an interface Service and the various services that I have, e.g. caching, lookup, logging etc, implement this interface.

PLAIN TEXT

JAVA:

/**
* Represents a service that the container can run.
*
*/
public interface Service {
/**
* Starts the service, may only be called if the service is not started.
*
* @throws IllegalStateException
* if called when the service is already started.
*/
public void start();
/**
* Indicates whether the service is started
*
* @return true if the service is started, false otherwise
*/
public boolean isStarted();
}

I have a test case for Service that tests that the various implementations of Service adhere to the general contract. I might have the following three tests:

PLAIN TEXT

JAVA:

public class ServiceTest {
private Service service;
@Test
public void shouldNotIndicatedStartedForNewObject() {
assertFalse(service.isStarted());
}
@Test
public void shouldStartIfNotAlreadyStarted() {
service.start();
assertTrue(service.isStarted());
}
@Test(expected = IllegalStateException.class)
public void shouldThrowExceptionIfStartedCalledOnAStartedService() {
service.start();
assertTrue(service.isStarted());
service.start();
}
}

If I have a caching and lookup service and I want to test that both adhere to the contract of the Service interface then I have to annotate the ServiceTest to indicate that it should run with the parameterized runner and provide an annotated factory method that returns a collection of arguments to run the tests with.

So the full testcase is:

PLAIN TEXT

JAVA:

@RunWith(Parameterized.class)
public class ServiceTest {
private Service service;
public ServiceTest(final Service service) {
this.service = service;
}
@Parameters
public static Collection implementations() {
return Arrays.asList(new Object[][] { { new CachingService() }, { new LookupService() } });
}
@Test
public void shouldNotIndicatedStartedForNewObject() {
assertThat(service, is(not(started())));
}
@Test
public void shouldStartIfNotAlreadyStarted() {
service.start();
assertThat(service, is(started()));
}
@Test(expected = IllegalStateException.class)
public void shouldThrowExceptionIfStartedCalledOnAStartedService() {
service.start();
assertThat(service, is(started()));
service.start();
}
}

The test classes for CachingService and LookupService now only need deal with testing the specifics of caching or lookups rather than testing adherence to the service specification.

I have yet to use this in production code on a large scale so we'll have to see how it works out, but it seems far better than having to replicate test code amongst several test cases.

junit.jar and Ant

Paul — Tue, 02 Jan 2007 23:58:09 +0000

At last no more messing about copying junit.jar or modifying your system classpath to get JUnit to work with Ant. Version 1.7 allows you to specify its location in a classpath element in your build file.

See the last point from the manual page for the JUnit task:

Note: You must have junit.jar available. You can do one of:
1. Put both junit.jar and ant-junit.jar in ANT_HOME/lib.
2. Do not put either in ANT_HOME/lib, and instead include their locations in your CLASSPATH environment variable.
3. Add both JARs to your classpath using -lib.
4. Specify the locations of both JARs using a element in a in the build file.
5. Leave ant-junit.jar in its default location in ANT_HOME/lib but include junit.jar in the passed to . (since Ant 1.7)

One thing to be careful of, make sure you include the junit.jar file that you want, you probably want to make the classpath element specifying the location of the junit.jar file the first classpath element in your junit task - I spent quite a bit of time trying to work out why the tests annotated with the new JUnit 4 @Test annotation weren't getting run only to eventually find a JUnit 3.1 junit.jar file from the Spring Framework in the classpath before the JUnit 4 junit.jar file.