12 Running JUnit Tests

Procedure for Converting Tests

This procedure describes how to set up files, property settings, and configuration settings before running a JUnit test.

1. Create a testsuite.jtt file in root of the product directory.

   For example, if the product unpacks into directory foo/, the testsuite.jtt file should be in that directory. It does not necessarily need to be co-located with the tests.

   The .jtt file is a properties formatted file, with key=value pairs on each line. Setting the name and id keys is mandatory. The name is a short descriptive name for your test suite, the id is an internal key used identify this test suite.

2. Select your method for scanning for tests by specifying a TestFinder class.

   The line for specifying the TestFinder class looks like this:

   finder = com.sun.javatest.junit.JUnitSuperTestFinder 
         -superclass junit.framework.TestCase
   

   See JUnitAnnotationTestFinder and JUnitAnnotationTestFinder for further information.

3. Select your TestSuite class, using com.sun.javatest.junit.JUnitTestSuite if you do not subclass it.

   Use a fully qualified class name. This class must be available on the system class path, preferably on the class path defined in your .jtt file. For example:

   testsuite = com.sun.javatest.junit.JUnitTestSuite
   

4. Specify the interview.

   If you don't have your own interview, use the line below as the default. This class must be available on the system class path, preferably on the class path setting in your .jtt file. For example:

   interview = com.sun.javatest.junit.JUnitBaseInterview
   

5. Provide a tests setting.

   The tests location is important because it is forwarded to the TestFinder class you specified in Step 2. This location is often relative to the location of the testsuite.jtt file as described in Step 2. Use forward slashes to make the path platform independent. Do not use absolute paths or relative paths to places above testsuite.jtt. One of the following lines might serve as an example:

   • If you are scanning .java files, they might be located below the tests/ directory.

     tests = tests
     

   • If you are scanning class files, they might be located below the classes/ directory:

     tests = classes 
     

   See JUnitSuperTestFinder and JUnitAnnotationTestFinder for further information.

6. Make sure that the paths to any classes you specify in the testsuite.jtt file are assigned to the classpath key in the testsuite.jtt file.

   This how the harness locates the classes. For example, if you specify:

   interview = com.sun.javatest.junit.JUnitBaseInterview
   

   be sure to add the path to the JAR file that contains that class to the classpath key as shown here:

   classpath = lib/jt-junit.jar lib/jt-myts.jar
   

7. Try running the harness to see if it finds your tests.

   You have to decide how to arrange your (JAR) files and resolve paths. The general form is:

   > cd mytestsuite/
   

   > java -jar lib/javatest.jar -ts .
   

   This starts the harness and forces it to load the test suite located in the current directory (represented by "."). The testsuite.jtt file must be located in the "." directory.

   When the main window comes up, you should see a tree populated with the tests you intended. Check the counters on the main panel to view a summary of the tests that were found. You can check the View > Properties menu item to verify that the plug-in classes are loaded as you expect.

JUnitSuperTestFinder

This class looks for a superclass that identifies the class as a JUnit test. By default it searches the ancestors of each class for junit.framework.TestCase. Because a test suite might require further derivations of junit.framework.TestCase to support its particular needs, you can use the -superclass option to specify a more specific class.

For example, consider the following class structure:

java.lang.Object
   junit.framework.TestCase
      foo.BetterTestCase
         product.Test0002a

Test0002a is a subclass of BetterTestCase, and so forth.

• If given Test0002a, JUnitSuperFinder ascends the inheritance chain until it reaches either a matching superclass or java.lang.Object. It searches for the TestCase class by default, so when given Test0002a, it ascends two levels, finds java.lang.Object, and returns Test0002a to the harness as a test.

• If this test finder is given java.util.ArrayList, it ascends until it reaches java.lang.Object, at which point it decides that the class is not a test and moves on.

To change the superclass for which you are scanning, supply the -superclass argument and specify a class name. You can supply this argument multiple times to scan for multiple superclasses. For example, in the testsuite.jtt file you might specify the following:

finder = com.sun.javatest.junit.JUnitSuperTestFinder -superclass
         foo.BetterTestCase -superclass foo.CustomTestCase

Although it does not execute tests, the test finder attempts to pick out test methods by looking for public methods that begin with the string "test". It then lists these in a space-separated list, without the parameters (just the method name). The list might contain duplicates because the full signature is not evaluated. Semantics for this TestDescription value are loosely defined at this point. Public comment is welcome (submit your comments to the JT harness interest forum at http://java.net/projects/jtharness).

This superclass finder generates the TestDescription (com.sun.javatest.TestDescription) values shown in Table 12-1.

JUnitAnnotationTestFinder

This annotation test finder scans classes for the org.junit.Test annotation. It uses the same scanning strategy as JUnitSuperTestFinder.

This annotation finder generates the TestDescription (com.sun.javatest.TestDescription) values shown in Table 12-2.

JUnitBareMultiTest

This is the execution class for JUnit 3.x style tests. Execution is accomplished using the class name supplied by the test finder (through the TestDescription) which is used to execute that class's TestCase.runBare() method. This might not be sufficient for all test suites. Output from stdout and stderr are captured. The test passes if no exceptions are thrown and fails if there are any Throwable results.

JUnitAnnotationMultiTest

This is the execution class for JUnit 4.x style tests. It takes the class that was identified by the test finder and executes it using the JUnit library TestResult.Section parts. Also, because execution is turned over to JUnit, it does not report any of its own debugging output during execution. (In the future, it would be useful to take more advantage of the Result API and any observer APIs that are available.)