8 The TestSuite Object

The JavaTest harness uses the TestSuite object as a portal to information about the test suite; whenever the JavaTest harness requires information about the test suite, it queries the TestSuite object. JavaTest reads the testsuite.jtt file to determine the class name and class path for the test suite; JavaTest then uses those properties to instantiate the TestSuite object. By default, the TestSuite object also gets a number of other standard properties from the testsuite.jtt file. As test suite architect, you create and maintain your TestSuite class and the testsuite.jtt file.

The testsuite.jtt File

The testsuite.jtt file is located in the top-level directory of the test suite and is a registry of information about the test suite that includes the paths to various JavaTest components as well as other static information about the test suite. The testsuite.jtt file generally contains at least two entries that tell the JavaTest harness how to start the TestSuite class:

A testsuite entry that specifies the name of the TestSuite class and any arguments the class requires
A classpath entry that specifies the class path on which the main TestSuite class can be found (typically, a JAR file that contains test suite-specific components). This entry is required if the TestSuite class or any other classes the TestSuite refers to are not located within javatest.jar.

The testsuite.jtt file usually contains other entries that specify information about the test suite; the JavaTest harness reads the file and passes the information to the TestSuite class when it starts. Table 8-1, "testsuite.jtt Properties" describes the standard properties used by the TestSuite and may be specified in the testsuite.jtt file:

Table 8-1 testsuite.jtt Properties

Property	Description
additionalDocs	An optional list of resource names that identify JavaHelp helpsets for documents to be added to the JavaTest Help menu. The content of the helpsets must be provided on the test suite classpath (see classpath above). Example: `additionalDocs=jck.hs` `releasenotes.hs`
classpath	Extends the class path beyond `javatest.jar`. The class path is used to locate JavaTest plug-in classes (script, finder, interview) in JAR files, Zip files, or directories. You must separate entries with white space; relative paths are relative to the test suite root directory. If not given, classes must be located on the main JavaTest class path (not recommended). Always use "`/`" as the file separator. Default: Nothing in addition to `javatest.jar` Example: `classpath=lib/jtdemotck.jar`
env.tsRoot	A specialized entry to allow a legacy (prior to JavaTest version 3.0) test suite to override the values of `$testSuiteRoot` and `$testSuiteRootDir` that get set in the environment used to run tests. Most test suites should not need to set this property.
finder	The name of the test finder class and arguments (if any). This property is used by the default implementation of `TestSuite.createTestFinder` to determine the test finder to be used to locate tests. This property should be of the form "classname args", where classname identifies the name of the test finder class itself; any arguments are passed to the test finder's `init` method. Example: `testsuite=com.sun.javatest.finder.TagTestFinder` The default implementation of `TestSuite.createTestFinder` uses the following logic to determine the test finder: If a `testsuite.jtd` file is found in the test suite `tests/` directory, or in the location specified in the testsuite.jtd entry of the `testsuite.jtt` file, the test finder is assumed to be `com.sun.javatest.finder.BinaryTestFinder` (which reads the `testsuite.jtd` file) If a finder entry is found in the `testsuite.jtt` file, it is used to determine the test finder If neither of the preceding are found, the default is to use `com.sun.javatest.lib.HTMLTestFinder` See the description of the testsuite.jtd entry below.
id	A unique identifier composed of letters, digits, underscore, minus, and hyphen used to identify a specific version of a test suite. The JavaTest harness uses this property to ensure that component versions are compatible. By convention, the name is composed of the following parts: technologyNameTCK_version. Example: `id=DemoTCK_tags_1.0`
initial.jtx	The path to the exclude list shipped with the test suite. If the path is relative, it is evaluated relative to test suite root directory. Always use "`/`" as the file separator. The recommended location for this file is in the test suite `lib/` directory. Example: `initial.jtx=lib/my_testsuite.jtx`
interview	The name of the interview class and arguments (if any). The default implementation of `TestSuite.createInterview` uses this property to determine the interview to use to obtain configuration information required to run the tests. The property should be of the form "classname args", where classname identifies the name of the interview class itself; any arguments are passed to the interview's `init` method. Example: `interview=com.sun.demotck.DemoInterview`
keywords	The list of valid keywords for this test suite. If the entry is present and contains a list of keywords, the keywords are added to the configuration editor keywords combo box. If the entry is omitted, it is taken to mean "unspecified" — in which case the user can use the configuration editor to specify keywords, but the configuration editor keywords combo box is disabled. If the entry is present but empty, it is taken to mean "none" — in which case the configuration editor does not present the keyword questions and tabs to the user.
latest.jtx	Specifies the location (as a URL) where the latest exclude list can be obtained. The `http:` and `file:` protocols are supported; authentication access is not yet supported. Example: `latest.jtx=http://my_company.com/support/exclude`
logo	Specifies the location on the class path of an image to be used as the test suite logo. The path is evaluated relative to the test suite root directory. This logo is displayed in the JavaTest Quick Start wizard.
name	The name of the test suite. This property is a string of up to 80 characters. By convention the name is composed of the following parts: technology_name TCK version\| Test Suite [(additional text)] Example: `name=DemoTCK 1.0 Test Suite (Tag Tests)`
script	The name of the test script class and arguments (if any). This property is used by the default implementation of `TestSuite.createScript` to determine the script to run the tests. The value should be of the form "classname args", where classname identifies the name of the `Script` class itself; any arguments are passed to the Script's `init` method. If this property is not specified, the default implementation of `TestSuite.createScript` reverts to the behavior defined for the JavaTest harness, version 2. Relying on this behavior is not recommended. Example: `script=com.sun.javatest.lib.StdTestScript`
serviceReader	Enables service management for the test suite. See Chapter 13 for detailed information about the service management feature.
testCount	The number of tests in the test suite. This property gives the JavaTest GUI a hint as to how many tests are in the test suite. Example: `testCount=450`
tests	By default, the JavaTest harness looks for test source files and test descriptions in the `tests/` directory in the test suite root directory. If you locate your test sources and test descriptions in a different directory, you must specify it using this property. Example: `tests=apitests`
testsuite	Optional class name for a custom `TestSuite` class. The value should be of the form "classname args", where classname identifies the name of the `TestSuite` class itself; any arguments are passed to the `TestSuite` `init` method. The `TestSuite` class is used to access virtually all information about the test suite. Defaults to `com.sun.javatest.TestSuite`, which provides default behavior in concert with the `testsuite.jtt` file. Default: `testsuite=com.sun.javatest.TestSuite`
testsuite.jtd	Can be used to override the default location of the BinaryTestFinder data file. By default the TestSuite class looks for a file named `testsuite.jtd` in the directory specified by the "tests" property in `testsuite.jtt`. To override the default, specify the name and location of the BinaryTestFinder data file relative to the top-level directory of the product (location of the `testsuite.jtt` file). Example: `testsuite.jtd=tests/testsuite.jtd`
tmcontext	Optional class name for a custom `ContextManager` class. The value should be of the form "classname", where class name identifies the name of the `ContextManager` class itself. The Test Manager (ExecTool) will query the test suite for this value as it builds the GUI. Defaults to `com.sun.javatest.exec.ContextManager`, which provides the default behavior of the harness. See Chapter 13 for more information on customization. Default: `tmcontext=com.sun.javatest.exec.ContextManager`

Note:

The testsuite.jtt file is a Java property file and follows all the standard rules for Java property files defined in java.util.Properties.

The following example shows the testsuite.jtt file that is included with the tag example test suite.

# Test Suite properties file for DemoTCK test suite with 
# tag-style tests
 
name=DemoTCK 1.0 Test Suite (Tag Tests)
id=DemoTCK_tags_1.0
classpath=lib/jtdemotck.jar
finder=com.sun.javatest.finder.TagTestFinder
script=com.sun.javatest.lib.StdTestScript
interview=com.sun.demotck.DemoTCKParameters

Overriding Default Methods

Although by default these properties are obtained from the testsuite.jtt file, you can override this behavior in your TestSuite class. By overriding the methods that get these properties, you can specify your own properties directly in the TestSuite class and/or manipulate the properties from testsuite.jtt as you wish. This is generally not necessary, but it is an option. Some reasons why you might choose to do this:

To hide or protect some of the properties
To determine some of these properties programmatically at runtime

To customize the TestSuite class, you must extend the base com.sun.javatest.TestSuite class. For details about which methods you may choose to override, see the TestSuite API documentation.