org.apache.commons.logging
Class PathableTestSuite

java.lang.Object
  extended by junit.framework.TestSuite
      extended by org.apache.commons.logging.PathableTestSuite
All Implemented Interfaces:
junit.framework.Test

public class PathableTestSuite
extends junit.framework.TestSuite

Custom TestSuite class that can be used to control the context classloader in operation when a test runs.

For tests that need to control exactly what the classloader hierarchy is like when the test is run, something like the following is recommended:

 class SomeTestCase extends TestCase {
  public static Test suite() throws Exception {
   PathableClassLoader parent = new PathableClassLoader(null);
   parent.useSystemLoader("junit.");
 
   PathableClassLoader child = new PathableClassLoader(parent);
   child.addLogicalLib("testclasses");
   child.addLogicalLib("log4j12");
   child.addLogicalLib("commons-logging");
 
   Class testClass = child.loadClass(SomeTestCase.class.getName());
   ClassLoader contextClassLoader = child;
 
   PathableTestSuite suite = new PathableTestSuite(testClass, child);
   return suite;
  }
 
  // test methods go here
 }
 
Note that if the suite method throws an exception then this will be handled reasonable gracefully by junit; it will report that the suite method for a test case failed with exception yyy.

The use of PathableClassLoader is not required to use this class, but it is expected that using the two classes together is common practice.

This class will run each test methods within the specified TestCase using the specified context classloader and system classloader. If different tests within the same class require different context classloaders, then the context classloader passed to the constructor should be the "lowest" one available, and tests that need the context set to some parent of this "lowest" classloader can call

  // NB: pseudo-code only
  setContextClassLoader(getContextClassLoader().getParent());
 
This class ensures that any context classloader changes applied by a test is undone after the test is run, so tests don't need to worry about restoring the context classloader on exit. This class also ensures that the system properties are restored to their original settings after each test, so tests that manipulate those don't need to worry about resetting them.

This class does not provide facilities for manipulating system properties; tests that need specific system properties can simply set them in the fixture or at the start of a test method.

Important! When the test case is run, "this.getClass()" refers of course to the Class object passed to the constructor of this class - which is different from the class whose suite() method was executed to determine the classpath. This means that the suite method cannot communicate with the test cases simply by setting static variables (for example to make the custom classloaders available to the test methods or setUp/tearDown fixtures). If this is really necessary then it is possible to use reflection to invoke static methods on the class object passed to the constructor of this class.

Limitations

This class cannot control the system classloader (ie what method ClassLoader.getSystemClassLoader returns) because Java provides no mechanism for setting the system classloader. In this case, the only option is to invoke the unit test in a separate JVM with the appropriate settings.

The effect of using this approach in a system that uses junit's "reloading classloader" behaviour is unknown. This junit feature is intended for junit GUI apps where a test may be run multiple times within the same JVM - and in particular, when the .class file may be modified between runs of the test. How junit achieves this is actually rather weird (the whole junit code is rather weird in fact) and it is not clear whether this approach will work as expected in such situations.


Constructor Summary
PathableTestSuite(Class testClass, ClassLoader contextClassLoader)
          Constructor.
 
Method Summary
 void runTest(junit.framework.Test test, junit.framework.TestResult result)
          This method is invoked once for each Test in the current TestSuite.
 
Methods inherited from class junit.framework.TestSuite
addTest, addTestSuite, countTestCases, createTest, getName, getTestConstructor, run, setName, testAt, testCount, tests, toString, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PathableTestSuite

public PathableTestSuite(Class testClass,
                         ClassLoader contextClassLoader)
Constructor.

Parameters:
testClass - is the TestCase that is to be run, as loaded by the appropriate ClassLoader.
contextClassLoader - is the loader that should be returned by calls to Thread.currentThread.getContextClassLoader from test methods (or any method called by test methods).
Method Detail

runTest

public void runTest(junit.framework.Test test,
                    junit.framework.TestResult result)
This method is invoked once for each Test in the current TestSuite. Note that a Test may itself be a TestSuite object (ie a collection of tests).

The context classloader and system properties are saved before each test, and restored after the test completes to better isolate tests.

Overrides:
runTest in class junit.framework.TestSuite


Copyright © 2001-2011 Apache Software Foundation. All Rights Reserved.