Chapter 31: JUnit API Reference

This chapter summarizes the JUnit API. Classes used by developers as part of their everyday testing are emphasized .

Package junit.framework

The junit.framework package contains all the classes developers need to begin writing JUnit tests. The TestCase class forms the center of the package, and developers subclass it to create automated unit tests. The rest of the classes in the package support TestCase: collecting its results, aggregating many instances into a test suite, and providing assertion facilities. The Test interface is another crucial package member ”it defines a common contract for TestCases and TestSuites, as well as providing a hook into the framework for extensions to use.

Class Assert

 public class Assert 

Inheritance Information

Extends: Object

Direct known subclasses: TestCase, TestDecorator

Description

Assert comprises a set of static assert methods that can be used to fail tests. Because TestCase and TestDecorator extend Assert, Assert's methods can be used by their unqualified names in subclasses of these two classes.

If the condition tested by the assert method evaluates to false, it throws an AssertionFailedError. The framework treats this error as a test failure. Assertion methods are used in TestCases to set up the pass/fail conditions for the test method.

Every Assert method is overloaded to take an additional String parameter as its first argument. This message will be attached to the AssertionFailedError, should it be thrown. The following code sample illustrates ways to use Assert's methods to verify that the code under test has produced the correct results.

 public void testOpenPortal(){   Portal hadesPortal = dimensionalGateway.openPortal(new Plane("Hades"));       /*verify that a portal object was returned*/   assertNotNull("null portal returned", hadesPortal);   /*verify the portal is open*/   assertTrue(hadesPortal.isOpen());   /*check that the portal has the correct name*/   assertEquals("portal name check", "HadesPortal", hadesPortal.getName());   /*try opening a portal to a plane that does not exist*/   try{     dimensionalGateway.openPortal(new Plane("xxxfooyyy"));     fail("should have gotten a PlaneNotFoundException e");   }   catch(PlaneNotFoundException e){/*behavior is as expected*/} } 

Methods

  assert(boolean condition)   Deprecated  public static void assert(boolean condition) 

Use assertTrue(boolean condition).

These are the most basic forms of assertions. If the boolean is not true, the assertion fails. The assert() and assert(String) methods were deprecated in favor of assertTrue() to avoid a conflict with the assert keyword in Java 1.4+.

  assert(String message, boolean condition)   Deprecated  public static void assert(String message, boolean condition) 

Use assertTrue(String message, boolean condition).

  assertTrue(boolean condition)  public static void assertTrue(boolean condition)  assertTrue(String message, boolean condition)  public static void assertTrue(String message, boolean condition)  assertEquals(String message, Object expected, Object actual)  public static void assertEquals(String message, Object expected,      Object actual)  assertEquals(Object expected, Object actual  public static void assertEquals(Object expected, Object actual  assertEquals(String message, double expected, double actual, double delta)  public static void assertEquals(String message, double expected,      double actual, double delta)  assertEquals(double expected, double actual, double delta  public static void assertEquals(double expected, double actual,      double delta)  assertEquals(String message, float expected, float actual, float delta)  public static void assertEquals(String message, float expected,      float actual, float delta)  assertEquals(float expected, float actual, float delta)  public static void assertEquals(float expected, float actual,      float delta)  assertEquals(String message, long expected, long actual)  public static void assertEquals(String message, long expected,      long actual)  assertEquals(long expected, long actual)  public static void assertEquals(long expected, long actual)  assertEquals(String message, boolean expected, boolean actual  public static void assertEquals(String message, boolean expected,      boolean actual  assertEquals(boolean expected, boolean actual)  public static void assertEquals(boolean expected, boolean actual)  assertEquals(String message, byte expected, byte actual)  public static void assertEquals(String message, byte expected,                                 byte actual)  assertEquals(byte expected, byte actual)  public static void assertEquals(byte expected, byte actual)  assertEquals(String message, char expected, char actual)  public static void assertEquals(String message, char expected,      char actual)  assertEquals(char expected, char actual)  public static void assertEquals(char expected, char actual)  assertEquals(String message, short expected, short actual)  public static void assertEquals(String message, short expected,      short actual)  assertEquals(short expected, short actual)  public static void assertEquals(short expected, short actual)  assertEquals(String message, int expected, int actual)  public static void assertEquals(String message, int expected, int actual)  assertEquals(int expected, int actual)  public static void   assertEquals(int expected, int actual) 

These methods compare the first (nonmessage) argument to the second and fail if they are not equal. The test for equality is == for primitives and equals() for objects. Floating-point comparisons are made with respect to the delta argument (that is, if the difference between expected and actual is greater than the delta, the test fails).

These comparisons require the delta because floating-point calculations can result in slight precision errors; these errors would cause a test that depended upon exact equality to fail even though the calculated result was as close to the desired result as floating point calculations could make it.

All the assertEquals methods automatically display the values of the expected and actual parameters as part of their failure message.

  assertNotNull(Object object)  public static void assertNotNull(Object object)  assertNotNull(String message, Object object)  public static void assertNotNull(String message, Object object)  assertNull(Object object)  public static void assertNull(Object object)  assertNull(String message, Object object)  public static void assertNull(String message, Object object) 

This method checks whether a given reference is null.

  assertSame(String message, Object expected, Object actual)  public static void assertSame(String message, Object expected,     Object actual)  assertSame(Object expected, Object actual)  public static void assertSame(Object expected, Object actual) 

This method verifies that the expected and actual arguments are the same object. This method uses the == method of comparison, not the .equals() method fail(String message).

 public static void fail(String message)  fail()  public static void fail() 

This method fails the test by throwing an AssertionFailedError. It s useful for asserting that a given point in code should not be reached, as with an exception that should have been thrown (see the example at the beginning of this section).

Interface Protectable

 public inteface Protectable 

Description

The JUnit framework and custom extensions use the Protectable interface to indicate code that requires JUnit-style exception handling. Developers can use an inner class to implement Protectable, defining its protect() method so that it calls relevant code (in the framework, calls to setUp(), the test method, and tearDown() are ultimately located within a protect() method). The Protectable can then be passed to a TestResult object, which will catch and log any exceptions resulting from the call to protect(). See TestResult.runProtected for details and an example. Everyday testing should not require the use of this interface.

Method

  protect()  public void protect() 

This method wraps a call to a method requiring protection. (Note: This method throws Throwable.)

Interface Test

 public interface Test 

Description

Part of the Composite design pattern, Test represents the common interface for single (TestCase), composite (TestSuite), and special (TestDecorator) tests. The shared interface allows all types of tests to be treated similarly by the framework.

Methods

  countTestCases()  public int countTestCases() 

This method counts the number of TestCases that will be run by this test (1 for TestCases, or the grand total of contained TestCases for suites).

  run(TestResult result)  public void run(TestResult result) 

This method runs this test and collects the results in the TestResult parameter.

Class TestCase

 public abstract class TestCase 

Inheritance Information

Extends: Assert

Implements: Test

Known subclasses: ExceptionTestCase

Description

TestCase is the central class of the JUnit framework. Subclasses of TestCase form the building blocks of automated test suites in JUnit. A TestCase subclass is usually designed to exercise the public interface of the class under test.

The standard template for a subclass is a String constructor, a setUp() method, a tearDown() method, and any number of (public) test methods named according to the form test < name of method to be tested > () . The setUp() method ensures that the test fixture is initialized , and the tearDown() method performs cleanup after a given test. When tests are run, each test method is run as part of a separate instance of the TestCase to which it belongs. The series of steps for test method execution is:

 setUp() <testMethod> tearDown() 

A test fixture is loosely defined as all the data and/or objects the test code needs in order to run properly. A TestCase for a sorting method might have a test fixture consisting of several unsorted arrays and a properly instantiated Sorter object.

Constructor

  TestCase(String name)  public TestCase(String name) 

TestCase() constructs an instance of the TestCase based on the name argument. TestCase follows the Pluggable Selector design pattern, in which the behavior of an object can modified externally. In the case of TestCase, this means each TestCase instance will run only one of its test methods when a caller invokes run(). Unless the behavior of runTest() is overridden, the name of the TestCase specifies which test method is executed.

Suppose a method testHeatUp()exercises heatUp() on a Weather object. To run this test method in the JUnit framework, we create a new TestCase with the following syntax:

 TestCase testToRunSoon = new WeatherTest("testHeatUp"); 

When run() is called on testToRunSoon, TestCase uses reflection to find and execute testHeatUp(). Subclasses should provide a String constructor that calls TestCase(String) to maintain this behavior.

Initialization code should be located in the setUp() method rather than in the constructor, a method called by the constructor, or an instance initializer block. See setUp() for more information.

Methods

  countTestCases()  public int countTestCases() 

This method returns the number of TestCases ”in other words, one.

  createResult()  public TestResult createResult() 

This method instantiates a new TestResult object.

  getName()  public String getName() 

This method returns the name of this TestCase instance. The name usually corresponds to the name of the method under test by this instance.

  name()   Deprecated  public String name() 

Use getName().

  run()  public TestResult run() 

This is a convenience method that runs the test case and returns a new TestResult containing the results.

 TestResult result = new WeatherTest("testHeatUp").run(); if (!result.wasSuccessful()){      sendIrateEmailToClassAuthor(); }  run(TestResult result)  public void run(TestResult result) 

This method runs the whole test, including setUp() and tearDown(), and collects the result in the TestResult argument. See the description of TestResult and Test for more information.

  runBare()  public void runBare() 

This method runs the TestCase, including setUp() and tearDown(). It provides no result-gathering functionality. If an exception is thrown during runBare(), the test has failed. This method is used mainly by the framework.

  runTest()  public void runTest() 

This method defines the testable behavior (as opposed to setup or result-gathering code) of this instance of the TestCase. The runTest() method is called as part of the run(TestResult) method. The default implementation uses reflection to run the method corresponding to the name of the TestCase.

Instead of using the default implementation, you can also override this method in an anonymous inner class to execute the desired test code. The following two methods of instantiating a WeatherTest that runs the testHeatUp() method are equivalent:

 TestCase innerClassCase = new WeatherTest("I could use any name here"){   public void runTest(){     testHeatUp();   } }; TestCase defaultCase = new WeatherTest("testHeatUp"); 

The anonymous inner class method of specifying TestCase behavior is more type safe and is described in the JUnit documentation. However, it seems to be primarily an artifact from an earlier version of JUnit where the reflection-based implementation did not exist. For most purposes, the reflection implementation is simpler.

  setName()  public void setName(String name) 

This method sets the name of the TestCase instance in a manner identical to the String constructor.

  setUp()  public void setUp() 

Because setUp() is called by TestCase before the execution of test code, subclasses should override this method to set up the test fixture for test methods to run against. Each test method in the class is executed within a separate instance of the TestCase, so there is no benefit in putting shared setup code in a constructor or an initializer block instead (because these will be run as often as setUp()).

In versions of JUnit previous to 3.7, exceptions generated in code that ran as part of TestCase construction yielded confusing stack traces ”all the more reason to stick to setUp().

All the test methods in the following subclass would now have access to a catalog with two products in it when executed with run(TestResult):

 public void setUp(){   /*initialize an instance variable.*/   testCatalog = new Catalog();   testCatalog.addProduct(new Product("Original Koozie"));   testCatalog.addProduct(new Product("Executive Chubber")); }  suite()  public static Test suite() 

The static suite() method is defined by convention in TestCase subclasses. It provides a convenient way of turning all the test methods in a TestCase into a single TestSuite. The suite() method can also be used by TestCases that define no test methods but instead serve as assemblers of other TestSuites. For TestCases with test code in them, suite() methods should probably follow this form:

 public static Test suite(){   //shortcut to add all test methods in the class   return new TestSuite(YourTestCase.class); } 

Alternatively, suite() can add the different TestCases to the suite by hand. This technique is convenient when you need more granularity (maybe a test method executes so slowly that you remove it temporarily during development):

 public static Test suite(){   //more granular implementation, add each test by hand   TestSuite suite = new TestSuite();   suite.addTest(new YourTestCase("testFirstMethod"));   //suite.addTest(new YourTestCase("testVerySlowMethod"));   return suite; } 

TestCases that serve as assemblers of other tests should use the following form:

 public static Test suite(){   TestSuite suite = new TestSuite();   suite.addTest(FirstClassInPackage.suite());   suite.addTest(SecondClassInPackage.suite());   //etc.   return suite; } 

The last implementation shows why it is conventional to define a suite() method for each TestCase() ”doing so makes it simpler for assembler TestCases to add all the tests in a package to their own suite() method.

  tearDown()  public void tearDown() 

This method tears down the test fixture. The tearDown() method is called by TestCase after the test method is finished. Generally , tearDown() should free shared resources such as database connections and perform cleanup. In addition, because a TestSuite may store instantiated and setup TestCases until the test run is complete, it is a good idea to dereference any memory- intensive instance variables :

 public void tearDown(){   databaseConnection.close();   testFile.delete();   giantArray = null; }  toString()  public String toString() 

This method returns a String representation in the form < name of instance >(< name of class >).

Interface TestListener

 public interface TestListener 

Description

The TestListener interface is used by the TestRunners provided by the JUnit framework. Its methods inform the listener object that a test has started, an error or a failure has been encountered , or a test has ended. These notifications allow the TestRunners to build a dynamic view of this information. TestListeners are registered with a TestResult.

Methods

  addError(Test test, Throwable t)  public void addError(Test test, Throwable t)  addFailure(Test test, AssertionFailedError t)  public void addFailure(Test test, AssertionFailedError t)  endTest(Test test)  public void endTest(Test test)  startTest(Test test)  public void startTest(Test test) 

Class TestFailure

 public class TestFailure 

Inheritance Information

Extends: Object

Description

The TestFailure class mates a failed Test with the exception that caused it to fail. It provides a constructor and accessor methods for the Test and the exception. The toString() method returns a short description of the failure.

Constructor

  TestFailure(Test failedTest, Throwable thrownException)  public TestFailure(Test failedTest, Throwable thrownException) 

Methods

  failedTest()  public Test failedTest()  thrownException()  public Throwable thrownException()  toString()  public String toString() 

Class TestResult

 public class TestResult 

Inheritance Information

Extends: Object

Description

TestResult is an example of the Collecting Parameter design pattern. The results of an arbitrary number of tests can be collected by passing the same TestResult to each Test's run method.

In addition to aggregating results, TestResult lets you run TestCases and interpret thrown exceptions as test failures. JUnit recognizes two types of negative Test result: failures and errors. Failures are the result of assertions that proved untrue at runtime and are represented by AssertionFailedErrors. Errors are unanticipated exceptions thrown by the test code (such as ClassCastExceptions). TestResult wraps both types of exceptions in TestFailure objects but stores them differently. In addition to exposing the collections of TestFailures, TestResult also provides a wasSuccessful() method to determine whether all tests passed.

TestResult is used mostly by the JUnit framework, because the provided TestRunners encapsulate code that displays the results of a test run. TestRunners interact with the TestResult through the TestListener interface. TestListeners are registered with the TestResult, which calls the appropriate methods to notify the listener of test lifecycle events (start, end, failure, and error). Here is an example of how we might use TestResult without the framework:

 TestResult result = new TestResult(); result.addListener(someCustomListener); nightlyTestSuite.run(result); if(!result.wasSuccessful()){   Enumeration eFailures = result.failures();   while(eFailures.hasMoreElements()){     TestFailure failure =(TestFailure)eFailures.nextElement();     System.out.println(failure.failedTest() + " failed with exception " +                        failure.thrownException());   }    if(result.failureCount() + result.errorCount() > 10){     printBigRedWarning();   } } 

Constructor

  TestResult()  public TestResult() 

Methods

  addError(Test test, Throwable t)  public void addError(Test test, Throwable t)  addFailure(Test test, AssertionFailedError t)  public void addFailure(Test test, AssertionFailedError t) 

These methods each add an error or failure to the TestResult. The second parameter in each case represents the exception that caused the test to fail.

  addListener(TestListener listener)  public void addListener(TestListener listener) 

This method registers a TestListener with this TestResult.

  endTest(Test test)  public void endTest(Test test) 

This method informs the TestResult (and by extension, its registered listeners) that the specified test is complete.

  errorCount()  public int errorCount() 

This method returns the number of detected errors stored in this TestResult.

  errors()  public Enumeration errors() 

This method returns an Enumeration of the detected errors stored in this TestResult.

  failureCount()  public int failureCount() 

This method returns the number of detected failures stored in this TestResult.

  failures()  public Enumeration failures() 

This method returns an Enumeration of the detected failures stored in this TestResult.

  removeListener(TestListener listener)  public void removeListener(TestListener listener) 

This method unregisters the specified TestListener.

  run(TestCase test)  protected void run(TestCase test) 

This method runs the specified TestCase and adds any thrown exceptions to the lists of failures or errors as appropriate.

  runCount()  public int runCount() 

This method returns the total number of TestCases whose results are gathered in this TestResult.

  runProtected(Test test, Protectable p)  public void runProtected(Test test, Protectable p) 

This method runs the given Protectable under JUnit protection (all caught exceptions, except ThreadDeathException, are added to the error/failure list). The runProtected() method is used internally as part of standard TestCase execution, and it can be used by extensions that execute code in addition to the code directly under test. Any exceptional conditions in the Protectable s protect() method are logged in the TestResult and associated with the Test parameter:

 //encapsulate database setup inside an anonymous Protectable Protectable p = new Protectable(){   public void protect(){     insertTestDataIntoDB();   } }; result.runProtected(testToAssociateFailuresWith, p);  runTests()   Deprecated  public int runTests() 

Use runCount().

  shouldStop()  public boolean shouldStop() 

This method checks whether a series of tests being run with this TestResult should stop (usually meaning prematurely). Users of TestResult can signal a premature stop with the stop() method.

  startTest(Test test)  public void startTest(Test test) 

This method notifies the TestResult (and its listeners) that the given Test will be started.

  stop()  public void stop() 

This method signals that the series of tests being run with this TestResult run should stop rather than finishing.

  testErrors()   Deprecated  public int testErrors() 

Use errorCount().

  testFailures()   Deprecated  public int testFailures() 

Use failureCount().

  wasSuccessful()  public boolean wasSuccessful() 

This method returns true if all the Tests run with this TestResult were successful, or false otherwise .

Class TestSuite

 public class TestSuite 

Inheritance Information

Extends: Object

Implements: Test

Direct known subclass: ActiveTestSuite

Description

TestSuite represents a composite of Tests. TestSuite implements the Test interface, so TestSuites can contain other TestSuites. Suites are generally used to collect and run all the test methods in a TestCase or all the TestSuites in a package. By nesting TestSuites within TestSuites, you can test portions of a codebase at an arbitrary level of granularity.

TestSuite handles exceptional conditions during Test addition (no valid constructor for the TestCase, exceptions in the constructor, no test methods found in the class during automatic addition, and so on) by adding a new Test to the suite that will fail automatically with an appropriate warning message.

Constructors

  TestSuite()  public TestSuite()  TestSuite(String name)  public TestSuite(String name) 

This constructor constructs an empty TestSuite. New Tests can be added to the suite by calling the addTest(Test) method.

  TestSuite(Class theClass)  

This constructor constructs a TestSuite containing a TestCase for each test method in the Class argument. Test methods are defined as public methods in the class that take no arguments, declare a void return type, and begin with the word test :

 TestSuite suite = new TestSuite(WeatherTest.class); 

Methods

  addTest(Test test)  public void addTest(Test test) 

This method adds the specified test to the TestSuite. It s used to hand construct a TestSuite ”usually for the purpose of adding other TestSuites to this suite:

 /*add a single Test*/ theSuite.addTest(new PortalTest("testOpenPortal")); /*suite() method returns the suite for that class*/ theSuite.addTest(WeatherTest.suite());  addTestSuite(Class testClass)  public void addTestSuite(Class testClass) 

This method adds all the test methods in the specified class to the suite. It s equivalent to a call to:

 addTest(new TestSuite(testClass));  countTestCases()  public void countTestCases() 

This method counts the total number of TestCases in this suite (including TestCases within contained TestSuites).

  getName()  public void getName() 

This method returns the name of this TestSuite (as specified by the String constructor or setName()). TestSuites are not required to have a name.

  run(TestResult result)  public void run(TestResult result) 

This method runs all the Tests (including TestCases and other TestSuites) contained within the suite. The total results are gathered in the TestResult. The run() method is usually called by one of the framework s TestRunners.

  runTest(Test test, TestResult result)  public void runTest(Test test, TestResult result) 

This method runs the given Test with the given TestResult. It s equivalent to test.run(result) in the default implementation. Subclasses can override runTest() to customize how Tests are run by the suite.

  setName(String name)  public void setName(String name) 

This method sets the name of the TestSuite.

  testAt(int index)  public Test testAt(int index) 

This method returns the Test at the given index. Tests are stored internally in a list, so the index corresponds to the position in the list (the first Test added is index 0, the second is index 1, and so on). The testAt() method is rarely used in everyday testing.

  testCount()  public int testCount() 

This method returns the number of Tests immediately contained by this suite (not the grand total number of Tests).

  tests()  public java.util.Enumeration tests() 

This method returns the Tests immediately contained by this suite as an Enumeration.

  toString()  public String toString() 

This method returns a String representation of the TestSuite. In version 3.7, this is the name of the TestSuite.