9 Test Finder

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.io.*;
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">
<tr>
  <td>title</td>
  <td>Checkbox Tests</td>
</tr>
<tr>
  <td>source</td>
  <td>CheckboxTest.java</td>
</tr>
<tr>
  <td>executeClass</td>
  <td>javasoft.sqe.tests.api.java.awt.Checkbox.CheckboxTests</td>
</tr>
<tr>
  <td>executeArgs</td>
  <td>-TestCaseID ALL</td>
</tr>
<tr>
  <td>keywords</td>
  <td>runtime positive</td>
</tr>
</table>

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.

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.

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

com.sun.javatest.finder.BinaryTestFinder

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

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