Unit testing and test driven development are proven ways to improve both the productivity of a developer and the quality of their software. JUnit and EasyMock are the predominant choices for testing tools in the Java space. This reference card will guide you through the creation of unit tests with JUnit and EasyMock. It contains detailed definitions for unit testing and mock objects as well as a description of the lifecycle of each. The APIs for both JUnit and EasyMock are covered thoroughly so you can utilize these tools to their fullest extent.

Unit Testing

A unit test is a test of a single isolated component in a repeatable way. A test consists of four phases:

JUnit is a popular framework for creating unit tests for Java. It provides a simple yet effective API for the execution of all four phases of a unit test.

A test case is the basic unit of testing in JUnit and is defined by extending junit.framework.TestCase. The TestCase class provides a series of methods that are used over the lifecycle of a test. When creating a test case, it is required to have one or more test methods. A test method is defined by any method that fits
the following criteria:

• It must be public.
• It must return void.
• The name must begin with “test”.

Optional lifecycle methods include public void setUp() and public void tearDown(). setUp()is executed before each test method, tearDown()is executed after each test method and the execution of both setUp() and tearDown() are guaranteed.

Figure 1

import junit.framework.TestCase;
public class FooTest extends TestCase {
        private Foo fooInstance;
        @Override
        public void setUp() {
        fooInstance = new Foo();
        }
public void testBar() {
        assertNotNull(“fooInstance was null”, fooInstance);
        String results = fooInstance.bar();
        assertNotNull(“Results was null”, results);
        assertEquals(“results was not ‘success’”,
        “success”, results);
        }
        @Override
        public void tearDown(){
      fooInstance.close();
}
}

Place test classes in the same package but different source folder as the class they are testing. That allows the test to have access to protected methods and attributes.

A JUnit test case can contain many test methods. Each method identified as a test will be executed within the JUnit test lifecycle. The lifecycle consists of three pieces: setup, test and teardown, all executed in sequence.

JUnit Lifecycle, continued

public void
setUp()

public void
testXYZ()

public void
tearDown()

Table 1. Lifecycle stage

All of the test methods are guaranteed to be executed. In JUnit 4 two more phases of the lifecycle were added, beforeClass() and afterClass(). These methods are executed once per test class (instead of once per test method as setUp and tearDown are), before and after respectively.

Table 2. Assertions

Testing is about running code with a predictable set of inputs and verifying that the set of outputs you receive are as expected. JUnit is used to execute the code to be tested in an isolated manor so that those validations can be made.

Figure 2

public void testGoodResultsBar() {
  String param1 = “parameter1”;
  String results = foo.bar(param1);
  assertNotNull(“results was null”, results);
  assertEquals(“results was not ‘good’”, “good”,
   results);
}
public void testBadResultsBar() {
  try {
    String results = foo.bar(null);
  } catch (NullPointerException npe) {
    return;
  }
  fail();
}

testGoodResultsBar() tests a positive scenario. It passes in an expected value (“parameter1”) into the method to be tested (foo.bar()) and validates that the results are as expected (the String “good”).

The second test is an example of a negative test. It tests that an error condition is handled correctly. In testBadResultsBar(), foo.bar() is passed null expecting that a NullPointerException will be thrown. If it is not thrown, the test is considered a failure (indicated by the fail() call).

JUnit 4 added annotations to the framework and eliminated the need to extend TestCase. You can direct both the lifecycle events and other aspects of the test execution with the provided annotations.

Table 3. Annotations

Figure 3 shows two test cases, one using JUnit 3.x method names and one using JUnit 4 annotations.

Figure 3

JUnit 3.x

import junit.framework.TestCase;
 public class FooTestCase extends TestCase {
 private Foo foo;
 @Override
 public void setUp() {
   foo = new Foo();
 }
 public void testGoodResultsBar() {
   String param1 = “parameter1”;
   String results = foo.bar(param1);
   assertNotNull(“results was null”, results);
   assertEquals(“results was not ‘good’”, “good”,
     results);
 }
 public void testBadResultsBar() {
   try {
 String results = foo.bar(null);
   } catch (NullPointerException npe) {
     return;
   }
 fail();
 }
 @Override
 public void tearDown() {
   foo.close();
 }
}

JUnit 4

public class FooTestCase {
   private Foo foo;
   @Before
   public void buildFoo() {
     foo = new Foo();
   }
   @Test
   public void testGoodResultsBar() {
     String param1 = “parameter1”;
     String results = foo.bar(param1);
     assertNotNull(“results was null”, results);
     assertEquals(“results was not ‘good’”, “good”,
      results);
   }
   @Test
   public void testBadResultsBar() {
     try {
                String results = foo.bar(null);
     } catch (NullPointerException npe) {
                return;
     }
     fail();
   }
        @After
        public void closeFoo() {
         foo.close();
   }
}

Test Suites

A test suite is a collection of tests cases. It is used to run a collection of tests and aggregate the results. In JUnit 3.x., test suites can be used to parameterize test cases (parameterized tests are handled with annotations in JUnit 4) as well as group test cases together (in functional groups for example). There are two ways to create a test suite, programmatically and with annotations.

Test Suites, continued

Programmatically:
TestSuite suite = new TestSuite();
suite.addTest(new MyFirstTest());
suite.addTest(new MySecondTest());
suite.addTest(new MyThirdTest());
suite.run();
Annotations:
@RunWith(Suite.class)
@SuiteClasses({FooTest.class, BarTest.class})
public class AllTests{
   public static Test suite() {
      return new JUnit4TestAdapter(AllTests.class);
   }
}

A test fixture is a baseline environment used for testing. For example, if the method bar is to be tested on the object foo, the test should create a new instance of foo for each test. This will prevent any state related issues from interfering with future tests (variables left initialized from previous tests, objects left with invalid data, etc). Figure 1 is an example of a fixture. It creates a new instance of foo for each test and closes it after the execution of each test. This prevents any carryover issues from affecting the current test.

Unit testing is the testing of a component in isolation. However,in most systems objects have many dependencies. In order to be able to test code in isolation, those dependencies need to be removed to prevent any impact on test code by the dependant code. To create this isolation, mock objects are used to replace the real objects.

EasyMock is a framework for creating mock objects using the java.lang.reflect.Proxy object. When a mock object is created, a proxy object takes the place of the real object. The proxy object gets its definition from the interface or class you pass when creating the mock.

EasyMock has two sets of APIs. One is intended for creation and manipulation of mock objects that are based on interfaces, the other on classes (org.easymock.EasyMock and org.easymock. classextensions.EasyMock respectively). Both provide the same basic functionality; however classextensions does not have quite as extensive as an API as the regular EasyMock does.

EasyMock has a lifecycle similar to JUnit. It contains four stages.

EasyMock Mock Object Lifecycle, Continued

Table 4. EasyMock stages

Table 5. Types of mock objects in EasyMock

Creating Objects with EasyMock

There are two main ways to create a mock object using EasyMock, directly and thru a mock control. When created directly, mock objects have no relationship to each other and the validation of calls is independent. When created from a control,all of the mock objects are related to each other. This allows for validation of method calls across mock objects (when created with the EasyMock.createStrictControl() method).

Direct Creation of Mock Objects

…
@Override
public void setUp() {
        UserDAO userDAO = EasyMock.createMock(UserDAO.class);
        CustomerDAO customerDAO =
        EasyMock.createMock(CustomerDAO.class);
}
…

Creation of a Mock Object Through a Control

…
@Override
public void setUp() {
        IMocksControl mockCreator = EasyMock.createControl();
        UserDAO userDAO = mockCreator.createMock(UserDAO.
         class);
        CustomerDAO customerDAO =
mockCreator.createMock(CustomerDAO.class);
}
…

Table 6 describes the API available for creating mock objects. These are static methods that are available on both versions of EasyMock (regular and classextension). createMock(MyInterface.class) is also available from a mock control.

Creating Objects with EasyMock, Continued

EasyMock.createMock(MyInterface.class)

EasyMock.createNiceMock(MyInterface.class)

EasyMock.createStrictMock(MyInterface.class)

Table 6. EasyMock method

There are three groups of scenarios that exist when recording behavior: void methods, non void methods and methods that throw exceptions. Each of which is handled slightly different.

Void Methods

Void methods are the easiest behavior to record. Since they do not return anything, all that is required is to tell the mock object what method is going to be called and with what parameters. This is done by calling the method just as you normally would.

Code Being Tested

…
foo.bar();
String string = “Parameter 2”;
foo.barWithParameters(false, string);
…

Mocking the Behavior

Foo fooMock = EasyMock.createMock(Foo.class);
fooMock.bar();
fooMock.barWithParameters(false, “Parameter 2”);
…

Methods That Return Values

When methods return values a mock object needs to be told the method call and parameters passed as well as what to return. The method EasyMock.expect() is used to tell a mock object to expect a method call.

Code to Be Tested

…
String results = foo.bar();
String string = “Parameter 2”;
BarWithParametersResults bwpr = foo.
barWithParameters(false, string);
…

Mocking the Behavior

…
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(foo.bar()).andReturn(“results”);
EasyMock.expect(foo.barWithParameters(false, “Parameter
2”))
  .andReturn(new BarWithParametersResults());
…

Methods That Throw Exceptions

Negative testing is an important part of unit testing. In order to be able to test that a method throws the appropriate exceptions when required, a mock object must be able to throw an exception when called.

Methods That Throw Exceptions, Continued

Code to Be Tested

…
try {
   String fileName = “C:\tmp\somefile.txt”;
   foo.bar(fileName);
} catch (IOException ioe) {
   foo.close();
}
…

Mocking the Behavior

…
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(fooMock.bar(“C:\tmp\somefile.txt”))
   .andThrow(new IOException());
foo.close();
…

Repeated Calls

There are times where a method will be called multiple times or even an unknown number of times. EasyMock provides the ability to indicate those scenarios with the

.times(),
.atleastOnce() and .anyTimes() methods.
…
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(foo.bar()).andReturn(“results”).
anyTimes();
EasyMock.expect(foo.barWithParameters(false, “Parameter
2”))
   .andReturn(new BarWithParametersResults()).
atLeastOnce();
…

.atLeastOnce()

.times(int min,
int max)

.anyTimes()

Table 7. Time methods

Matchers in EasyMock

When replaying recorded behavior in EasyMock, EasyMock uses the .equals() to compare if the passed parameters are what are expected or not. On many objects, this may not be the desired behavior (arrays are one example). EasyMock has a collection of matchers to solve this issue. Matchers are used to compare things in ways other than the .equals() method. Custom matchers can be created by implementing the org.easymock. IArgumentMatcher interface.

Matcher in Action

...
String [] array1 = {“one”, “two”, “three”};
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(fooMock.getMiddleElement(
EasyMock.aryEq(array1)).andReturn(“two”);
…

eq(Object obj)

anyBooelan(),anyByte(),
anyChar(), anyDouble(),
anyFloat(), anyInt(),
anyLong(), anyObject,
anyShort()

eq(float x, float range),
eq(double x, double range)

aryEq(Array x)

isNull()

notNull()

same(Object x)

isA(Class clazz)

lt(NumericPrimitave x),
leq(NumericPrimitave x),
geq(NumericPrimitave x),
gt(NumericPrimitave x)

startsWith(String x),
contains(String x),
endsWith(String x)

and(x, y), or(x, y), not(x)

Table 8. Matcher in action

Once the behavior of the mock objects has been recorded with expectations, the mock objects must be prepared to replay those expectations. Mock objects are prepared by calling the replay() method and passing it all of the mock objects to be replayed.

Replaying Expectations in EasyMock

…
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(fooMock.doSomething(parameter1,
parameter2)).andReturn(new Object());
EasyMock.replay(fooMock);
…

The final step in the mock object lifecycle is to validate that all expectations were met. That includes validating that all methods that were expected to be called were called and that any calls that were not expected are also noted. To do that, EasyMock.verify() is called after the code to be tested has been executed. The verify() method takes all of the mock objects that were created as parameters, similar to the replay() method.

…
Foo fooMock = EasyMock.createMock(Foo.class);
EasyMock.expect(fooMock.doSomething(parameter1,
Parameter2)).andReturn(new Object());
EasyMock.replay(fooMock);
Bar bar = new Bar();
bar.setFoo(fooMock);
EasyMock.replay(fooMock);
bar.runFoo();
EasyMock.verify(fooMock);
…

JUnit provides a basic set of functionality that is applicable to all types of testing. JUnit extensions are projects that add on features that are specific to a particular type of testing. Table 9 shows a list of the more popular extensions.

Table 9. JUnit Extensions

The internet holds a large collection of resources on test driven development, JUnit and EasyMock. Table 10 lists just a few of the more popular resources.

Table 10. Resources