Testing Toolbelt: JUnit

The JUnit framework is arguably the de-facto standard for unit testing java code, and is also the basis of many other testing frameworks (unit or otherwise). Using the JUnit framework, one can quickly run a test method, class, or suite and get one of three responses:

• Success: All of the assertions in the test method passed, no fail calls were encountered, and no unexpected exceptions were thrown.
• Failure: One of the assertions in the test method failed or a fail call was encountered.
• Error: An unexpected java.lang.Throwable was thrown within the test method's body.

For the sake of brevity, and since I am mostly using Java 1.6 these days, this discussion will focus on JUnit 4.4 which is based on annotations and static imports instead of specially-named methods and the extension of the junit.framework.TestCase class.

@Test

Every method that should be run as a test should be annotated with the org.junit.Test annotation. The Test annotation must be used on only public void methods and the annotated method can only take parameters when used in conjunction with the Parameterized annotation discussed below. The Test annotation can take two optional arguments:

expected

An optional argument to the Test annotation which declares that the test method is expected to throw a Throwable of the defined type. If the method does not throw a Throwable of an appropriate type, the test will fail. If any other Throwable escapes the method body, the test will be considered in error.

timeout

An optional argument to the Test annotation which declares that the test method is expected to complete within the defined number of milliseconds. If the method does not return in time, the test fails.

@Before/@After/@BeforeClass/@AfterClass

Public methods marked with these annotations will be run before each test (setUp()), after each test(tearDown()), before each test suite, or after each test suite. These annotations are usually used to setup and reset the environment in which the tests are running.

Assert

The org.junit.Assert class is expected to be used through the use of static imports, and contains a large number of static methods which can be used to ensure that the elements of a test are in an expected state. Each of the assert* methods has two forms:

assert*(actual, expected)

performs the assertion and fails with a default failure message.

assert*(message, actual, expected)

performs the assertion and fails with a custom failure message. (sometimes in addition to the default message)

Here are some of the main assertion methods:

assertNull(param)/assertNotNull(param)

Asserts that the parameter is(not) null-valued.

assertTrue(param)/assertFalse(param)

Asserts that the parameter is true|false?

assertEquals(actual, expected)/assertArrayEquals(actual, expected)

Asserts that actual and expected are equal().

fail(message)

Causes the current test to immediately fail. Use this when writing custom assert methods or when creating new empty test methods.

assertThat(actual, Matcher)

The entry point into the Hamcrest Matcher framework, which will be covered by itself in a different post. This method, when used in conjunction with a Matcher instance is more capable, and produces more helpful failure output than the other JUnit assert* methods.

Parameterized

The org.junit.runners.Parameterized class is a non-default JUnit TestRunner implementation which allows for the creation of a series of test class instances, one for each of the parameter sets defined in the parameter generation method. Each of these test class instances will then be executed.

Every class which uses the Parameterized class as a runner must provide a source method for the parameters. The parameter source method is marked using the org.junit.runners.Parameters annotation. The parameter source method must be static and return a Collection of values or arrays. Each element in the returned collection represents a single test class execution and will be passed to the constructor for a new instance of the test class. The constructor must accept the same number of arguments and those arguments must be of a compatible type to those contained in each element of the returned collection.

An example of Parameterized usage:

/*
 * This test class, when run, produces results showing
 * three test runs with two successes and one failure.
 */
@RunWith(Parameterized.class)
public class ParameterizedTest {
  final Integer value;

  @Parameters public static Collection<integer> getParameters() {
    return Arrays.asList(1, 3, 10);
  }

  public ParameterizedTest(final Integer value) {
    this.value = value;
  }

  @Test public void isLessThanFive() {
    assertTrue(this.value < 5);
  }
}