Package junit.extensions

The junit.extensions package contains a few useful classes that add functionality to the basics contained within junit.framework. In addition to these, the package contains the TestDecorator class that serves a superclass for third-party extensions to the framework. See Chapter 14 for examples of how JUnitPerf uses the TestDecorator class to add functionality to existing JUnit TestCases.

Class ActiveTestSuite

 public class ActiveTestSuite 

Inheritance Information

Extends: TestSuite

Description

This is a subclass of TestSuite that runs each of the Tests in the suite in its own thread. The suite does not finish running until the last thread has terminated . ActiveTestSuite does not extend its multi-threaded nature to contained suites. In other words, if an ActiveTestSuite A, contains a normal TestSuite B, all of B's tests will execute within the single thread that A assigns to B (unless B specifies some other behavior).

To employ an ActiveTestSuite, simply instantiate it and use it as you would a normal TestSuite. Individual tests can be hand-added to the suite, or all of the test methods in a class can be added. The following code samples illustrate both approaches.

 //Create an ActiveTestSuite by hand-adding several copies of the same //Test--perhaps to test performance in a multi-threaded environment: TestSuite suite = new ActiveTestSuite(); suite.addTest(new YourTestCase("testFirstMethod")); suite.addTest(new YourTestCase("testFirstMethod")); suite.addTest(new YourTestCase("testFirstMethod")); //Replace the standard suite() method so that it uses an ActiveTestSuite public static Test suite(){   //shortcut to add all test methods in the class   return new ActiveTestSuite(YourTestCase.class); } 

Methods

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

This method runs each Test contained by the suite in its own thread.

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

This method spawns a new thread and runs the specified Test within it.

Although TestResult synchronizes many of its methods to provide a measure of thread safety, calling runTest(Test, TestResult) on an ActiveTestSuite will result in a new, unsupervised thread. Unless you have a good reason to do so, it is probably not worth calling this method externally.

  runFinished(Test test)  public void runFinished(Test test) 

This method notifies the suite that a test thread is about to complete.

The runFinished() method may be public by mistake. Calling this method externally could result in premature termination of the suite (before all Tests are run).

Class ExceptionTestCase

 public class ExceptionTestCase 

Inheritance Information

Extends: TestCase

Description

ExceptionTestCase is a subclass of TestCase that expects a specified exception when run and fails if one is not thrown. This class seems to be of dubious usefulness . If it were subclassed, all instances of the subclass would expect the exception specified in the constructor. As a result, it would be impossible to put test methods that did not throw the exception into such a subclass. If ExceptionTestCase is not subclassed, no convenient way exists to specify which method the TestCase instance should run as the code under test. Anonymous inner classes could solve this problem, but are hardly easier than the alternate syntax for checking an exception:

 try{   codeUnderTest();   fail("expected an ExpectedException"); } catch(ExpectedException e){/*ignore*/} 

Constructor

  ExceptionTestCase(String name, Class exception)  public ExceptionTestCase(String name, Class exception) 

This constructor constructs the test with the specified name and class of the exception expected to be thrown when the test runs.

Method

  runTest()  protected void runTest() 

This method runs this test case. If an exception of the class specified in the constructor is not thrown, the test fails.

Class RepeatedTest

 public class RepeatedTest 

Inheritance Information

Extends: TestDecorator

Description

RepeatedTest is a simple TestDecorator that runs the decorated Test the number of times specified by the constructor. The constructor expects the interface Test (as do most TestDecorators) so that TestCases or TestSuites are all valid targets for repetition (other TestDecorators are also valid targets for repetition ”see the code samples for JUnitPerf's use of RepeatedTest in Chapter 14) . The run(TestResult) method simply calls run(TestResult) on the decorated Test the specified number of times. Generally, this means that setUp() and tearDown () are called for each repetition on each contained TestCase. However, any fixture set up or dismantling that occurs outside of these methods (such as in the constructor of a TestCase) will not be executed multiple times because run() is called multiple times on the same instance of the Test.

Constructor

  RepeatedTest(Test test, int repeat)  public RepeatedTest(Test test, int repeat) 

This constructor specifies the Test to decorate and the number of repetitions.

Methods

  countTestCases()  public int countTestCases() 

As specified in the Test interface, this method counts the total number of TestCases contained in the Test. In the case of RepeatedTest, this count is arrived at by multiplying the number of repetitions by the result of a call to countTestCases() on the decorated test.

  run(TestResult result)  public void run(TestResult result)  toString()  public String toString() 

Class TestDecorator

 public class TestDecorator 

Inheritance Information

Extends: Assert

Implements: Test

Direct known subclasses: RepeatedTest, TestSetup

Description

TestDecorator is the preferred base class for extensions that decorate (add additional behavior to) Tests. TestDecorator implements Test, so it can be used to decorate suites or TestCases; in addition, decorators can be nested within other decorators. TestDecorator defines the basic structure of a decorator and provides a few convenience functions. Test developers extend TestDecorator and override the run(TestResult) method to provide custom Test decoration.

Constructor

  TestDecorator(Test test)  public TestDecorator(Test test) 

This constructor constructs a TestDecorator that wraps the specified Test. Subclasses should provide a constructor that calls this constructor.

Methods

  basicRun(TestResult result)  public void basicRun(TestResult result) 

Subclasses can call this method during their own run() method to run the wrapped test without any decoration. See the run() method for an example of use.

  countTestCases()  public int countTestCases() 

This method counts the total number of TestCases run by this Test. Subclasses should override this method if the decoration code affects how many TestCases are actually run.

  getTest()  public Test getTest() 

This method returns the contained Test that is decorated.

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

This method runs the contained Test in cooperation with the decoration code. This is the key place for subclasses to define such code:

 public class RandomTest extends TestDecorator{   public RandomTest(Test test){     super(test);   }   public void run(TestResult result){     if(Math.random() > .5){       basicRun(result);     }   } } 

Although this decorator violates XP principles (why would you ever not run a test?), it shows how decorators can add functionality to a Test.

  toString()  public String toString() 

This method simply returns toString() on the enclosed Test in the base implementation. Subclasses should override it to provide additional description of the decoration.

Class TestSetup

 public class TestSetup 

Inheritance Information

Extends: TestDecorator

Description

TestSetup is a base class for decorators that wish to provide additional fixture setup and teardown. If TestSetup decorates a TestSuite, it's setUp() and tearDown() methods will be executed once for all the tests within the suite. Therefore, subclasses of TestSetup are an ideal place to put expensive set up code (such as the insertion of test data into a database) that does not need to be repeated for each individual test.

Uncaught exceptions resulting from setUp() or tearDown() code are caught and logged in the TestResult as associated with the TestSetup instance. The following subclass sets the specified system properties before the contained test runs:

 public class PropertiesSetup extends TestSetup{   java.util.Properties props;   public PropertiesSetup(Test test, java.util.Properties props){     super(test);     this.props = props;   }      protected void setUp(){     System.getProperties().putAll(props);   }   protected void tearDown(){     for(Iterator i= props.keySet().iterator(); i.hasNext();){         System.getProperties().remove(i.next());     }   } } 

Methods

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

This method runs setUp(), then the enclosed Test, and then tearDown().

  setUp()  protected void setUp() 

Subclasses should override this method to provide additional one-time fixture code surrounding the decorated Test.

  tearDown()  protected void tearDown() 

Subclasses should override this method to dismantle the fixture created by setUp() after the contained Test has run.