JavaTest Harness Architect's Guide, JavaTest Harness 4.4.1 for the Java Platform E20663-02 |
|
Previous |
Next |
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:
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).
The test finder creates one TestDescription
object per test from the information it reads from the test description.
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.
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.
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.
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>
Table 9-1 Test Description Table
Title | Checkbox Tests |
---|---|
source |
CheckboxTest.java |
executeClass |
|
executeArgs |
|
keywords |
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.
Note: 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.
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 |
---|---|
|
Puts |
arguments |
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
Specifies where the set of compressed test descriptions is written. The output file always contains the
Defines the end of the finder specification |
test-suite |
The path to the directory in the test suite that contains the test descriptions (typically, the |
tests |
An optional list of directories in which to search for test descriptions (typically, directories under |
Note: 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:
com.sun.javatest.finder.BinaryTestFinder
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