Skip Headers
JavaTest Harness Architect's Guide,
JavaTest Harness 4.5 for the Java Platform
  Go To Table Of Contents
Go To Index


9 Test Finder

After the TestSuite object is created, the JavaTest harness starts the test finder for the test suite. The TestFinder class creates the object responsible for finding and reading test descriptions — information required to execute a test is provided in its test description. At a basic level, the TestFinder class does the following:

  1. Given an object (for example, a file) that contains a test description, the test finder uses the read() method to read the object. The read() method in turn calls the scan() method that must be provided by the test finder. The scan() method scans the file object for a test description or any references to other files that must be read (for example, if the file object is a directory).

  2. The test finder creates one TestDescription object per test from the information it reads from the test description.

  3. The getTests() method returns any test description information that it finds, and the getFiles() method returns a list of any other files that it must read to locate other tests.

Test Finder Subtypes

Because test descriptions can be embodied in a wide variety of formats, you can extend the base TestFinder class, customizing the read() method to meet the test suite's needs. The JavaTest Architect's release provides library classes that you can use directly; however, these classes do not provide much error checking. You can conveniently subtype a library class to provide additional validity checking.

Tag Test Finder

The TagTestFinder extends the TestFinder class. This class is also provided so that you can further extend and customize it to your own needs.

The TagTestFinder looks for test description information in specially commented tags in Java programs and shell scripts. The TagTestFinder recursively scans test directories looking for files with the .java extension and extracts test description information embedded directly in the test source files using specialized tags. These tags are located with Java language comments and begin with the @ character. The following figure shows an example of a file that contains tag test description entries.

/* @test
 * @bug 4105080
 * @summary Activation retry during a remote method call     
 * to an activatable object can cause infinite recursion in
 * some situations. 
 * @author John Brown
 * @bug 4164971
 * @summary Allow non-public activatable class and/or
 * constructor Main test class has a non-public
 * constructor to ensure functionality is in 
 * place
 * @library ../../../testlibrary
 * @build TestLibrary RMID
 * @build ActivateMe CheckActivateRef_Stub CheckActivateRef
 * @run main/othervm/policy=security.policy/timeout=240 
import java.rmi.*;
import java.rmi.server.*;
    public class CheckActivateRef
    extends Activatable
    implements ActivateMe, Runnable
    private CheckActivateRef(ActivationID id, MarshalledObject obj)
    throws ActivationException, RemoteException
    super(id, 0);

This format has the advantage of being very convenient for the test developer.

Examples of tag test descriptions can be found in jt_install\examples\javatest\simpleTags\demotck\tests.

HTML Test Finder

An example of a test finder that reads HTML test descriptions is the JCKTestFinder — a subtype of the HTMLTestFinder class that provides additional error checking. The JCKTestFinder is described in some detail here to demonstrate how a test finder works. HTMLTestFinder is provided with the JavaTest harness so that you can further extend it and customize it to your own needs.

Test suites that use the HTMLTestFinder class use HTML-based test descriptions to provide the information required to execute their tests. Distributed throughout the directories that contain the tests are HTML test description files that contain one or more test description tables. Each HTML test description table contains information about a single test (for example, its name in the class path). Every test must be represented by its own unique test description table; however, test description files can contain multiple test description tables. Test description tables are always assigned the HTML class "TestDescription" using the class attribute:

<TABLE BORDER="1" class="TestDescription">

The following HTML source produces the test description table that follows:

<table border="1" class="TestDescription">
  <td>Checkbox Tests</td>
  <td>-TestCaseID ALL</td>
  <td>runtime positive</td>

Table 9-1 Test Description Table

Title Checkbox Tests




-TestCaseID ALL


runtime positive

The JCKTestFinder test finder locates the HTML test description files by recursively scanning directories to look for files with the .html suffix, ignoring any other types of files. It reads the test description table, ignoring all information in the file except the content of the basic table tags.

If you include multiple test description tables in a single test description file, each test description table must be preceded by an <A NAME> HTML tag that provides a unique identifier for each test description table.


Test description files should also contain comments and text that describe the test.

The HTMLTestFinder class can also check the validity of test description values. For example, the HTMLTestFinder can be run with flags that cause error messages to be printed if any of the test description fields are invalid. When you extend HTMLTestFinder, you can add your own validity checks.

The benefit of this format is that it makes it easy and convenient for users to browse test descriptions using the JavaTest harness GUI or a web browser. The trade-offs are that more work is required of the test developers to create and maintain the HTML files, and parsing these separate files has an impact on performance.

Examples of HTML test descriptions can be found in jt_install\examples\javatest\simpleHTML\demotck\tests.

Binary Test Finder

BinaryTestFinder was created to improve the startup performance of large test suites. It is capable of reading test description information from a highly optimized format created from any type of native test description.

The optimized format (filename.jtd) is created using a companion program called BinaryTestWriter. BinaryTestWriter uses a native test finder such as HTMLTestFinder, or TagTestFinder to find and read native test descriptions (for example, HTML files or source tags) and then creates a single, optimized file that contains the test description information for all the tests in the test suite. If one is available for the test suite, the test suite uses the BinaryTestFinder to read test descriptions from that optimized file. Use of the BinaryTestFinder is highly recommended for larger test suites — it greatly reduces the time required to populate the JavaTest harness test tree.


BinaryTestWriter is a standalone utility that creates compressed file that contains a a set of binary test descriptions. It uses a test finder that you specify to locate the test descriptions for your test suite, and writes a compact representation of those test descriptions to a file that can be read by BinaryTestFinder (described in the next section).

BinaryTestWriter is run from the command line as follows:

java -cp javatest.jar com.sun.javatest.finder.BinaryTestWriter arguments test-suite[tests]

The following table describes the parts of the command:

Table 9-2 BinaryTestWriter Command Components

Component Description

-cp javatest.jar

Puts javatest.jar on the class path


-finder finderClass [finderArgs] -end

Specifies the test finder to use to locate the test descriptions in the specified test suite.

finderClass: The name of the plug-in class for the desired test finder. The class must be on the class path used to run BinaryTestWriter.

finderArgs: Any optional arguments passed to the test finder's init method.

-o output-file

Specifies where the set of compressed test descriptions is written. The output file always contains the .jtd suffix and is typically named testsuite.jtd. The testsuite.jtd file is usually placed in the test suite tests/ directory.


Defines the end of the finder specification


The path to the directory in the test suite that contains the test descriptions (typically, the tests/ directory)


An optional list of directories in which to search for test descriptions (typically, directories under tests/)


The finderClass, finderArgs, test-suite arguments are specified here exactly as they are when you run the JavaTest harness without using BinaryTestWriter.


BinaryTestFinder is a standard JavaTest test finder that knows how to read test descriptions stored in the file written by BinaryTestWriter. The full name of the class is:


The BinaryTestFinder class is provided in the standard javatest.jar file. You can use it through the standard string interface, or directly via the API. For details about the API, see the Javadoc documentation.

There are two ways you can use BinaryTestFinder:

  • If you use the standard TestSuite class, you can place testsuite.jtd in the test suite tests\ directory. If the file is found there it is used, otherwise the uncompressed files in this directory are used.

  • Specify the finder explicitly in the testsuite.jtt file:

    finder=com.sun.javatest.finder.BinaryTestFinder -binary testsuite.jtd

    This method requires that testsuite.jtd be present when the test suite is run. If it is not present, the tests are not run and an error condition exists. You can use the testsuite.jtd property in the testsuite.jtt file to specify the location of the testsuite.jtd file. You must remember to run BinaryTestWriter before running the test suite.

  • Override the createTestFinder method for the TestSuite class you provide for your test suite. This method allows you to dynamically determine whether to use BinaryTestFinder. The TestSuite class can check for the existence of the binary test description file (testsuite.jtd) before running tests; if the .jtd file is not found, it can choose to use an alternate finder.


The following example shows the command line used to start the basic non-customized TestFinder class:

java -cp lib/javatest.jar com.sun.javatest.finder.BinaryTestWriter
-finder com.sun.javatest.lib.HTMLTestFinder -dirWalk
-end top_level_testsuite_dir/tests

This example shows the command line for starting a customized TestFinder class (MyTestFinder). The finder class takes -dirWalk and -specialMode as arguments. Note that the JAR file that contains the custom finder class (in this case lib/mytck.jar) is added to the class path.

java -cp lib/javatest.jar:lib/mytck.jar com.sun.javatest.finder.BinaryTestWriter 
-finder com.sun.mytck.lib.MyTestFinder -dirWalk 
-specialMode 2 -end top_level_testsuite_dir/tests