4 Creating a Test Suite

Create a Test Suite Directory

Create the directory and sub-directories for your test suite.

1. Create the top-level test suite directory.

   Create the directory somewhere convenient in your file system. This directory is referred to as ts_dir for the remainder of this chapter.

2. Under ts_dir, create sub-directories named tests, lib, and classes.

Create the testsuite.jtt File

As described in Chapter 3, the JavaTest harness reads the testsuite.jtt file to find out information about your test suite. The following steps describe how to create the testsuite.jtt file for this test suite.

1. Make ts_dir the current directory.

2. Create the testsuite.jtt file.

   Enter the following information into a text editor:

   # Test Suite properties file for DemoTCK test suite 
   # with tag-style tests
   name=My Test Suite
   id=1.0
   finder=com.sun.javatest.finder.TagTestFinder
   script=com.sun.javatest.lib.StdTestScript
   interview=com.sun.javatest.interview.SimpleInterviewParameters
   

   You can substitute your own string values for the name and id properties.

   
   

   Note: The classpath entry is not used here because the Standard Test Finder, Standard Test Script, and Simple Interview classes are all contained within javatest.jar which is automatically on the class path. If you create your own components, you must include the classpath entry to point to the JAR file that contains these classes. See Chapter 8 for more information about the testsuite.jtt file.

   
   

   Save the file as ts_dir\testsuite.jtt.

Copy javatest.jar

The test suite works best if there is a copy of the javatest.jar file in the lib directory of the test suite; this enables the JavaTest harness to automatically locate the test suite.

1. Copy javatest.jar from jt_install\examples\javatest\simpleTags\demotck\lib to ts_dir\lib.

   
   

   Note: The javatest.jar file contains the SimpleInterview class that is used with this test suite (com.sun.javatest.SimpleInterview.Parameters). As your test suite becomes more complicated and customized, you may need to create a custom interview. See Chapter 6 for more information.

   
   

Set Up the classes Directory

In order to execute, tests must have access to some of the classes contained in javatest.jar. Extracting these classes eliminates the need for each test to have javatest.jar on its class path. The the most convenient location to place these classes is the ts_dir\classes directory.

1. Make ts_dir\classes the current directory.

2. Verify that the Java SE platform (version 1.6 or later) is in your path.

   At a command prompt, enter:

   C:\> java -version
   

3. From javatest.jar, extract the classes required to run the tests.

   Use the following command line:

   jar -xvf ..\lib\javatest.jar com\sun\javatest\Test.class
   com\sun\javatest\Status.class
   

   
   

   Note: As your test suite become more complex, you may have to add additional libraries to the classes directory.

   
   

Use a Simple Test Template

The following instructions describe how to create a very simple test to add to your test suite. For more detailed instructions about writing TCK tests, see the Test Suite Developers Guide.

1. Make ts_dir\tests the current directory.

2. Enter the test code into your favorite text editor.

   The following template can be used as the basis for writing simple tests:

   import java.io.PrintWriter;
   import com.sun.javatest.Status;
   import com.sun.javatest.Test;
   /** @test
     * @executeClass MyTest
     * @sources MyTest.java
    **/
   public class MyTest implements Test{
       public static void main(String[] args) {
           PrintWriter err = new PrintWriter(System.err, true);
           Test t = new MyTest();
           Status s = t.run(args, null, err);
           s.exit();
       }
       public Status run(String[] args, PrintWriter log1, PrintWriterlog2) {
           Status result;
           // your test code here ...
           return result;
       }
   }
   

   Note that the section delimited with the /** **/ characters is the test description portion of the test. It must be present for the JavaTest harness to locate and recognize the test. You will change all instances of MyTest, and replace the line // your test code here... with your own code. The following table describes the test description entries recognized by the Standard Test Script:

   Test Description Entry	Description
   test	Identifies the comment block as a test description and the containing file as a test
   executeClass	Specifies the name of the test's executable class file (assumed to be located in the classes directory)
   executeArgs	Specifies arguments (if any) that the test accepts
   sources	Names the source files required to compile the test. This entry is required if you use the JavaTest harness to compile your tests. See Chapter 7 for more information. This tag is also used by the JavaTest harness to display a test's sources in the Files tab of the Test pane.
   keywords	Specifies user-defined keywords that direct the JavaTest harness to include or exclude tests from a test run.

   
   

   You can create simple tests by replacing the comment:

   // your test code here ...
   

   with code that tests your API. Note that the test must return a Status object as a result.

   
   

   Note: You can find examples of simple tests at: jt_install\examples\javatest\simpleTags\demotck\tests

   
   

Create and Compile a Simple Test Example

The following sample is a very simple test you can use to get started.

1. Save the following file as MyTest.java.

   Be sure to copy the entire file, including the test description delimited with the /** **/ characters

   import java.io.PrintWriter;
   import com.sun.javatest.Status;
   import com.sun.javatest.Test;
    
   /** @test    
     * @executeClass MyTest
     * @sources MyTest.java
    **/
    
   public class MyTest implements Test {
       public static void main(String[] args) {
           PrintWriter err = new PrintWriter(System.err, true);
           Test t = new MyTest();
           Status s = t.run(args, null, err);
           s.exit();
       }
    
       public Status run(String[] args, PrintWriter log1, PrintWriter log2) {
           Status result;
           if (1 + 1 == 2)
               result = Status.passed("OK");
           else
               result = Status.failed("Oops");
           return result;
       }
   }
   

2. Compile MyTest.java.

   Use the following command on WIN32 systems:

   C:\> javac -d ..\classes -classpath ..\classes MyTest.java
   

   Use the following command on Solaris or Linux systems:

   % javac -d ../classes -classpath ../classes MyTest.java
   

   MyTest.class is created in the ts_dir\classes directory. As you add more and more tests you should organize them hierarchically in subdirectories.

   
   

   Note: As you add more and more tests, you may want to use the JavaTest harness to compile the tests. For more information, see Chapter 7.

   
   

Run a Test Suite

You are now ready to run the test suite.

1. Make ts_dir the current directory.

2. Start the JavaTest harness.

   At a command prompt enter:

   c:\> java -jar lib\javatest.jar -newdesktop
   

   
   

   Note: The -newdesktop option is used here to ensure that the JavaTest harness starts up like it did in the tutorial — under normal circumstances you should not use this option. For information about JavaTest options, see the online help.

   
   

3. Run the tests the same way you ran the tests in Chapter 2.

   The configuration interview for this test suite contains a question not included in the tutorial configuration interview. Use the following information to answer the question:

   Question Title	Answer	Description
   Class Path	ts_dir\classes	The test uses library classes located in the classes directory. Click the Add button to activate a file chooser. Select the classes directory and click the Add File button.

   
   

Top-Level Test Suite Directory

The top-level test suite directory generally contains the following files and directories:

The Test Suite JAR File

All of the components you create for the test suite should be delivered to the user in a single JAR file installed in the lib directory of the test suite. The JAR file is added to the class path in the testsuite.jtt file as described in Chapter 8. Experience has shown that it is best to organized the JAR file with the following directory structure:

com\
  your_company\
     your_product\
     Interview class files and resource files, More Info help

For example, the JAR file for the demo TCK test suite:

        jt_install\examples\javatest\simpleTags\demotck\jtdemotck.jar

is organized like this:

com\
  sun\
     demotck\
     Interview class files and resource files, More Info help

If you provide a large number of components, you can further organize them into sub-packages:

com\
  your_company\
     your_product\
     Interview class files and resource files, More Info help
         lib\
         Everything else (TestSuite, Script, Finder, etc.)

Class Paths

When you create a test suite, it is important to keep in mind the three potential class paths that are involved:

• JavaTest class path

• Agent class path

• Test class path

Two of the ways described in the following sections in which you can set a class path are through a CLASSPATH environment setting or through a -classpath flag in the command line. The CLASSPATH environment setting is generally a safe way to set the classpath, although setting it as an environment variable is less explicit than using the -classpath flag.

The -classpath flag to the particular software development kit tool (such as java and javac) is generally the best way to set the class path if you know it explicitly. The main disadvantage of using the -classpath flag is that it overrides the CLASSPATH environment setting.

Shell example:

% CLASSPATH=otherclasses javac -classpath classes -d out foo/

In this example, only classes set by -classpath are on the classpath. The otherclasses set by the CLASSPATH environment setting are dropped.

Shell example:

% CLASSPATH=otherclasses javac -classpath $CLASSPATH:classes d out foo/

In this example, the environment setting is added to the -classpath argument. The resulting classpath is otherclasses:classes.