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


6 Creating a Configuration Interview

As you design your test suite, you must decide how to provide the JavaTest harness with all of the information required to execute your tests. Some of this information is static — it is known prior to runtime through the test description mechanism. However, some information cannot be determined ahead of time and differs based on the context in which the tests are run. This information is called the configuration and is obtained from the user through a configuration interview that you design. The configuration interview is presented to the user in the JavaTest configuration editor and consists of a series of simple questions that the user answers. The interview exports the answers in a format called a test environment that the JavaTest harness understands.

This chapter describes how to create and package a configuration interview.

Designing Your Configuration

This section focuses on the design of the configuration information and how to determine what information is necessary to run your tests suite.

What is a Configuration?

The configuration provides the JavaTest harness with the information it needs to execute tests. This information falls in the following categories:

  • Information required by the script to execute the tests

  • Information required by tests. This information augments the test description and usually consists of information that changes based on the test execution context (for example, the platform or network).

  • Information that determines which tests to include or exclude from a test run

These categories are discussed in the following sections.

Test Script Information

A test script is responsible for running your tests. The test script knows the series of steps required to execute each test. It typically relies on test commands to perform each step and you design your configuration to provide the test commands (and their arguments) that the test script uses to execute each test. Test commands are Java classes that the test script instantiates to run tests.

As an example, the Standard Test Script uses a single step to execute tests; that step is defined in the configuration entry called command.execute. The configuration interview is responsible for setting the value of command.execute so that the Standard Test Script uses the appropriate command and arguments. For example, you can tell the Standard Test Script to use the ExecStdTestOtherJVMCmd command which executes tests in a process on the same computer that runs the JavaTest harness:

command.execute=com.sun.javatest.lib.ExecStdTestOtherJVMCmd args

If you intend to execute the tests differently; for example, on a different computer, you would define command.execute differently in your configuration. For a list of test commands included with the JavaTest release, see Appendix A. For information about creating custom test commands, see Chapter 10.

Test Description Entries

In the previous chapters of this manual, you have seen that most test descriptions are static; these entries consist of values that are known ahead of time and can be specified directly. In some cases these arguments cannot be determined ahead of time, especially test arguments (executeArgs). For example, tests that test network APIs may require the names of hosts on the network to exercise the API. If the test suite runs in different locations and on different networks, these values cannot be known ahead of time by the test developer. The configuration interview is expected to collect this information and make it available to the test.

A script may allow the test developer to specify variables in some test description entries that are defined in the configuration; these variables are prefixed with the "$" character. For example the Standard Test Script allows variables in the executeArg entry; in the case of a network test, here is what the test description might look like:

/** @test
  * @executeClass MyNetworkTest
  * @sources
  *@executeArgs -host $testHost -port $testPort

The arguments to the executeClass and sources entries are static — they are known ahead of time and do not change based on the context in which the test runs. The host names or IP addresses cannot be known ahead of time and are specified as variables to which the JavaTest harness assigns values when the test is run. The test suite's configuration interview asks the user to specify the values of the hosts and port numbers required to run the test; the values of $testHost and $testPort are defined from those answers. The configuration interview creates entries in the test environment as name/value pairs. For example:


Which Tests to Run

The JavaTest harness provides a number of ways that the user can specify which tests in the test suite to run. These standard values can be specified by the user in the configuration editor window question mode or quick set mode. You can easily include interview questions that gather this information at the end of the interview for you and require no extra work on your part.

Designing Your Interview

The goal of the configuration interview is to create (or export) a test environment. The test environment consists of one or more command templates that the test script uses to execute tests and the set of name/value pairs that define values required to run the tests.

The previous section described how to think about the kinds of configuration values your test suite needs; this section focuses on how you collect configuration values and translate them into test environment entries.

Command Strings

The most complex test environment entries are almost always the command strings the test script uses to execute the tests. A command string is a template that specifies the command used by the test script to execute the test. A command string contains symbolic values (variables) whose values are provided when the test is executed.

The complexity of these entries is determined by the versatility required by the test suite. If the test suite is always run on the same computer, in the same network, the command string is probably very easy to specify. In many cases the computing environment varies considerably, in which case the command strings are built up largely from answers that users provide in the configuration interview.

As previously described, test scripts depend on test commands to know how to execute tests in specific ways. The JavaTest release contains a set of standard library test commands that you can use to execute tests. The following table describes the most commonly used test commands. These test commands are described in more detail in Appendix A.

Table 6-1 Commonly Used Test Commands

Test Command Description


Executes a simple API test in the same JVM as the caller. Typically used with the JavaTest Agent.

ActiveAgentCommand PassiveAgentCommand

Execute a subcommand on a JavaTest Agent running in active or passive mode

If your platform requires a custom agent in order to run tests, use the test command designed for use with that agent.

Commands and command templates are described in more detail in Chapter 10.

The examples in this section show how to create command entries for the Standard Test Script using two of these commands: ActiveAgentCommand and ExecStdTestOtherJVMCmd.

Example 1

The Standard Test Script uses the value of the command entry command.execute to execute tests. If the tests are executed on the same computer running the JavaTest harness, a typical command entry for the Standard Test Script looks something like the following:

   C:\JDK\bin\java.exe -classpath $testSuiteRootDir\classes
   $testExecuteClass $testExecuteArgs

The portion of the entry to the left of the "=" is the name of the test environment entry, the portion to the right is the command string.

Let's examine the command string in detail:


The first part of the command string is the name of the test command class used to execute the test classes. In this example the command executes tests in a process on the same computer that runs the JavaTest harness.

Interview implications:

Your configuration interview specifies the command to use to execute the tests. If the API you are testing always runs in a known computing environment, your interview might create this part of the entry without input from the user. However, if the API being tested can be run in different ways, you must ask the user which way they choose to run it and provide the appropriate test command based on the user's input.

Imagine an API that can be tested on the same computer running the JavaTest harness, or on a different computer on the same network. In this case the interview must determine which way the user intends to run the tests and provide the appropriate command — ActiveAgentCommand or ExecStdTestOtherJVMCmd.

-classpath ts_dir\classes

The class path required by the tests. Replace ts_dir with the path to your test suite. To enhance performance, you should place all library classes required to run the test classes in the classes directory.

See Test Environment Variables for a list of available variables.

Interview implications:

You can determine the path to your test suite inside your interview. See Exporting the Test Environment for details. If the test classes require no additional classes be on the class path other than the ones you provide in the test suite's classes directory, your interview can insert the class path value directly into the entry without asking the user for input. If additional class path entries may be required, your interview may include questions that ask the user to provide additional entries that your interview appends to the class path.

This environment entry that can get more complicated if the test suite may be run using different versions of the Java runtime. Some Java runtime systems do not use the -classpath option; for example, they might use a syntax such as -cp or /cp. Additionally, some systems use the ":" character as the class path separator and others use the ";" character. If this is the case, your interview must include additional questions that determine the platform on which the tests are run so that you can create the appropriate command entry.


The path to the Java runtime command used to execute the test classes.

Interview implications:

This path almost certainly differs from user to user, so almost any interview must obtain this path from the user. The interview libraries include a question type named "file" that is very useful for obtaining path names.

Although no additional options or arguments are shown in this example, many Java runtimes or test suites require additional options and arguments. If your tests require any additional options, you include them in additional portions of the entry.


A variable that represents the name of the test class. The test script obtains the class name from the executeClass entry in the test description and provides it at runtime.

Interview implications:

The interview adds the variable to the environment entry.


A variable that represents the arguments specified in the test description. The test script obtains this value from the test description and provides it at runtime.

Interview implications:

The interview adds the variable to the environment entry.

Example 2

For this example, imagine a test suite that runs in a limited environment — it always runs on a remote system using the JavaTest Agent in passive mode. The command entry looks like this:

   -host myHost -port 501 
   $testExecuteClass $testExecuteArgs

Although this command is quite long, because of its limitations most of it is boilerplate; the only values that your interview has to gather from the user are the arguments to the -host and -port options.

Test Environment Variables

The following variables are available for use in test descriptions if you use the Standard Test Script or a test script derived from it. If you create a custom test script, it can provide additional values.

Table 6-2 Test Environment Variables

Variable Name Definition


The value for the executeArgs parameter from the test description of the test being run


The value of the executeClass parameter from the test description of the test being run


The value of the source parameter defined in the test description of the test being run. Valid only when using the JavaTest harness to compile a test suite. See Chapter 7.

Writing Your Interview

The previous two sections focused on the design of your configuration and your interview; this section focuses on writing the code to implement the interview.

This section takes a high-level view of the process of writing configuration interviews; complete, working code examples are provided separately from this manual. These examples are described in the following subsections.

Demo TCK interview

The Demo TCK is a simple test suite created to demonstrate the basic principles of writing and running test suites. The Demo TCK was featured in Chapter 7. The source code and More Info files for the configuration interview used in the Demo TCK test suite are included in the JavaTest Architect's release at the following location:


Demo Interview

The Demo Interview is a self-documenting JavaTest interview that demonstrates all of the interview question types, and other important interview techniques. A special viewer allows you to view the source of a question as you run it. Follow these instructions to start the Demo Interview:

Start the Demo Interview

  1. In a command window make the following your current directory:


  2. Start the Demo Interview test suite

    At the command prompt enter:

    C:\>java -jar lib\javatest.jar -newDesktop

    The -newdesktop option is used here to ensure that the JavaTest harness loads the correct test suite. For information about JavaTest options, see the online help.

  3. Choose Configure > New Configuration to start the interview

    Follow the directions in the interview. You can also browse the source for the interview at:


Interview Classes

Interviews are built from the following classes:


The top-level class used to build JavaTest configuration interviews. This class is a special subtype of com.sun.interview.Interviewthat provides the API required by the JavaTest harness. You do not normally use this class directly, see BasicInterviewParameters below.

com.sun.interview.Question (and its subtypes)

Questions are the primary constituent elements of interviews. Questions provide text and appropriate controls and serve as a place to store the user's response.


The base interview class. This class is used directly to implement sub-interviews (if any).


A subtype of com.sun.javatest.InterviewParameters that provides standard questions for all of the "standard" configuration values (for example, which tests to execute). You usually subtype this interview and expand it to obtain your specific test environment information. The BasicInterviewParameters class is flexible, see Putting it All Together for details.

For more information about these classes, please refer to the API documentation available in doc\javatest\api.

To create a configuration interview, you normally provide a subclass of the BasicInterviewParameters class and add questions to the interview. This class is responsible for collecting all test environment and standard value information and providing it to the JavaTest harness.

Interviews can contain nested sub-interviews. The choice of whether to break interviews into smaller sub-interviews is a design decision based on manageability — generally interviews over 20 questions are candidates for this kind of hierarchical organization. Interviews often contain a number of branches, and these branches are also often good candidates for becoming sub-interviews. Sub-interviews directly extend com.sun.interview.Interview.

The Current Interview Path

As mentioned in the previous section, interviews are often composed from sub-interviews that branch off of the main interview. During the interview process, branches of the interview can become inactive because the user changes the answer to a question; the branch can become reactivated if the user later changes the answer back. When a user completes a configuration interview, the answers to all questions the user has ever answered are stored on disk in an interview data file with the .jti extension. Because active and inactive questions are present in the interview data file, whenever the JavaTest harness needs configuration information (for example, to run tests or to display the environment) the JavaTest harness must determine the current interview path.

To determine the current interview path, the JavaTest harness starts at the first question and queries each question for the next question on the path, attempting to reach the Final question (see Table 6-3 for a description of different question types). If it does not reach the Final question, the interview is considered incomplete; the test configuration cannot be exported and the test suite cannot be run until the missing questions are answered. If the user attempts to run the test suite with an incomplete interview, they are asked whether they want to complete the interview at that time — if they do, the configuration editor is activated.

Determining the Next Question

Every question except the Final question must provide a getNext() method that determines the next (successor) question. The successor question can be fixed (constant) or determined based on the answer of a current question or on the cumulative answers of multiple preceding questions. Questions can also provide no successor question (by returning null). Lack of a successor question usually means that the current question is unanswered or contains an error; in that case the interview is incomplete.

You may add questions to the interview that gather no configuration information, they are only used to determine the next question in the interview. These are typically Choice questions used to determine a branch point in the interview. For example, you might include a question that asks the user whether they want to execute the tests locally (on the computer running the JavaTest harness) or on a remote computer using the JavaTest agent. Depending on the answer, you branch to the questions that gather information about how to run the JavaTest Agent.

Error Checking

If the user provides an invalid answer to a question, the interview cannot proceed. You use the boolean isValueValid() method to check the validity of an answer before you proceed to the getNext() method. You can handle error conditions in two ways: by returning null which causes the configuration editor to display the "Invalid response" message in red at the bottom of the question pane, or by making the successor question an Error question that causes the configuration editor to display a pop-up window with an error message that you provide (see ErrorQuestion in ).

Generally, an "Invalid response" message is sufficient if the error is a simple one; for example, if the user answers an integer question with a letter. However, for more subtle errors (for example, if an answer conflicts with a previous answer), it is necessary to provide more information to the user in a pop-up window.

Exporting the Test Environment

As previously mentioned, one of the goals of the interview is to produce a test environment. The JavaTest harness uses the InterviewParameters class's getEnv() method to obtain the test environment.

If you extend BasicInterviewParameters to create your interview, it provides an implementation of the getEnv() method that uses the values you export.

If, however, you extend InterviewParameters directly, you must provide a getEnv() method that gathers answers from the main interview and any sub-interviews and returns an TestEnvironment object. The best and simplest way to implement the getEnv() method is to use the interview's export() method, which in turn calls the export() method of each question on the current interview path that provides one. Note that an interview does not normally override/provide export()— it is provided automatically. When it is time to export the test environment, the getEnv() method calls export() to gather their test environment information. These questions export their values into a Map object from which you can construct a test environment. For detailed examples see the source code examples in the jt_install\examples directory.

When exporting the test environment, you can use the getTestSuite() method to get information about the test suite. This information (for example, the location of the test suite) is often useful in building test environment entries.


It is generally a very good idea for the controlling question to precede the questions that collect a given value, because the question text can provide information to the user about the series of questions coming up.

Question Types

The Question class is a base class that provides the different types of questions that you use to build your interview. You need not concern yourself about the GUI layout of a question; the configuration editor automatically determines the presentation of each question based on the question's type.

The following table lists all of the question types and shows (when applicable) how they are represented in the configuration editor.

Table 6-3 Question Types

Question Type Description GUI


A set of independent boolean choices

Set of named checkboxes Surrounding text describes choicearrayq.gif.


A set of alternative choices

Combo box or radio buttons, depending on the number of choices

Surrounding text describes choiceq.gif.


A pseudo question used to present error messages

Pop-up dialog box


A single file

Type-in field with associated file chooser

Surrounding text describes fileq.gif.


A set of files

A list box with an associated file chooser

Surrounding text describes filelistq.gif.


1. A pseudo question that marks successful completion of the interview

Text only, no user input

2. A pseudo question that marks the end of a sub-interview

For internal use only; never displayed


A floating point value (optional min./max. values)

Either slider or type-in field depending on the range

Surrounding text describes floatq.gif.


An IPv4 or IPv6 address

Either four integer fields, each of value 0 - 255, or a type-in field with a lookup button.

Surrounding text describes inetaddressq.gif. Surrounding text describes ipv6q.gif.


An integer value

Either slider or type-in field depending on the range

Surrounding text describes intq.gif.


A pseudo question used for sub-interviews; see interview.callInterview(...) in the API

For internal use only; never displayed


A list of complex values built from a set of questions.

A list box that displays the current contents of the list. The following questions add or edit a selected value in the list. This sequence is automatically terminated by a corresponding marker question.

Surrounding text describes filelistq.gif.


Expository text; generally used to introduce a set of questions

Text only; no user input


Enables configuring multiple key-value pairs in a single question.


String information

Type-in field that optionally includes suggested answers

Surrounding text describes stringq.gif.


A list of strings

A list box

Surrounding text describes filelistq.gif.


A tree selection

A tree selection GUI based on JTree

Surrounding text describes treeq.gif.


A convenience choice question for Yes/No answers

Radio buttons

Surrounding text describes yesnoq.gif.

Designing Your Questions

Be sure to break down complex environment entries into simple values that can be answered by a single question, then build up the entry from those values. For example, if you are creating an environment entry that requires the name of a remote host and its port address, it's best not to ask for both pieces of information in a single question, but to ask for each piece of information in a separate question.

For example, the following entry (previously seen in Example 1) could be built up from a number of interview answers:

   C:\JDK\bin\java.exe -classpath $testSuiteRootDir\classes
   $testExecuteClass $testExecuteArgs
  • Questions to determine whether the user plans to run the test locally or on a remote computer, and whether they plan to run the tests in the same JVM as the JavaTest Agent

  • A question to determine the path of the Java runtime command

  • One or more questions to determine the class path

  • Questions that determine the path separator on the test platform

Landing Point Questions

You might find it convenient and useful to include questions that do not gather any information, but rather provide space between sections of the interview or provide a frame of reference to the user about where they are in the interview. You can use the Null question type for this type of interview question. In some cases you can use landing points as bridges between the main interview and sub-interviews.


If your interview contains a large number of questions, you can break it up into sub-interviews. To create a sub interview, create a subtype of an Interview class. For example:

class MySubInterview extends Interview {

The constructor should take a reference to the parent interview as an argument, and this reference should be passed to the superclass constructor. This identifies this interview as a sub-interview of the parent interview. For example:

MySubInterview(MyParentInterview parent) {
       super(parent, "myTag");

In the constructor, use the setFirstQuestion method to specify the first question in the sub-interview. Subsequent questions are found in the normal way using the getNext method. For example:

MySubInterview(Interview parent) {
   super(parent, "myTag");

By default, a sub-interview shares a resource file and More Info help files (see Creating Question Text and More Info) with its parent interview (another reason to pass in that parent pointer). You can choose to use a different resource file and HelpSet if you want, although that is not typical for simple or moderately complex interviews. See the API specifications for setResourceBundle and setHelpSet for details.

At the end of the interview, have the last question return an instance of a FinalQuestion. This FinalQuestion is only a marker and does not have any question text, More Info, or a getNext method. For example:

Question qXXX = ......... {
   Question getNext() {
      return qEnd;
Question qEnd = new FinalQuestion(this);

For the parent interview to use a sub-interview, it must first create an instance of the sub-interview. This should be created once and stored in a field of the interview. For example:

Interview iMySubInterview = new SubInterview(this);

To call the sub-interview, use callInterview in a getNext method. The callInterview method takes two parameters — a reference to the interview to be called, and a follow-on question to be called when all the questions in the sub-interview have been asked. When the JavaTest harness sees the FinalQuestion at the end of a sub-interview, it goes back to where the interview was called and automatically uses the follow-on question that was specified there. For example:

Question getNext() {
   return callInterview(iMySubInterview, qFollowOnQuestion)
Flow Charts

Experience has shown that flow charting tools can be very helpful if the interview becomes large and complicated. These tools can help you track the logical flow of the interview and keep track of sub-interviews.

Putting it All Together

To write a configuration interview, you must provide a class that implements the abstract class InterviewParameters. This class provides the JavaTest harness access to both the environment values and to the standard values. Standard values are configuration values used by the JavaTest harness to determine:

  • Which tests in the test suite to run

  • How to run them

To simplify this task, the JavaTest harness provides an implementation called BasicInterviewParameters that does a lot of the work for you. This class provides a standard prolog, questions for all the standard values, and a standard epilog. All you have to do is to implement the methods and questions for your test environment. However, you can also customize the other parts of the interview if you wish to.

The questions in BasicInterviewParameters are divided into the following groups:

Table 6-4 Interview Question Groups

Group Description


Identifies the interview and provides helpful information to the user about the interview such as how many questions the average interview consists of and how to proceed. Optionally, provides questions about the environment name and description.


The questions you write to gather information for the test environment


Allows users to specify sub-branches of test trees as a way of limiting which tests are executed during a test run


Allows uses to filter tests based on keyword values. Test suites can associate keywords with tests so that the keywords can be used as a basis for including and excluding tests from test runs.

prior status

Allows users to include and exclude tests based on their outcome in a prior test run. Test can be excluded and included based on the following status values: passed, failed, not run, error (test could not be run).


Allows users to run tests concurrently on multi-processor computers

timeout factor

A value that is multiplied against a test's default timeout if a larger timeout is needed. The default timeout is 10 minutes.


Informs the user that they have completed the interview. May also provide information about how to run tests.

The groups of questions are presented in the order shown. Each group provides a method that identifies the first question in its group. The last question in the group uses another method to determine the next question. By default, the next question is the first question of the following group.

Figure 6-1 shows the "first" and "next" questions for each group of questions.

Figure 6-1 Interview Question Group First/Next Question Methods

Description of Figure 6-1 follows
Description of "Figure 6-1 Interview Question Group First/Next Question Methods"

In most cases you only need to concern yourself with the environment group. For all the other groups, BasicInterviewParameters provides standard questions. If you find that you must customize the standard questions, you can replace the questions for a group by redefining getXxxFirstQuestion() to get your custom questions. In this case, you must also override the methods that provide access to these configuration values. See the API for more details.

If you find that any of the standard questions do not apply to your test suite, you can override the getXxxFirstQuestion() question of any group you wish to skip so that it directly returns that group's getXxxSuccessorQuestion(). This circumvents the code that executes the group's questions and jumps directly to the next group. For example, if your test suite does not use keywords, you can override the getKeywordsFirstQuestion() method and implement it so that it returns getKeywordsSuccessorQuestion() as shown in Figure 6-2, "Skipping the Keywords Standard Question".

Figure 6-2 Skipping the Keywords Standard Question

Description of Figure 6-2 follows
Description of "Figure 6-2 Skipping the Keywords Standard Question"

Providing the Prolog

The standard prolog always contains a standard welcome question; it also contains optional environment name and description questions. By default, the name and description questions are not displayed. You can enable the name and description questions by calling the setNameAndDescriptionInPrologEnabled method in your interview.

If the standard prolog questions do not meet your needs, you can override the prolog with one of your own. Specify your prolog by means of the standard setFirstQuestion() method of the interview. At the end of your prolog you must call the getPrologSuccessorQuestion() method to determine the first question of the next group.

Providing the Environment Group

This section describes the basic tasks necessary to write the environment portion of the interview. Unless your test suite requires you to make changes to the standard questions (prolog, standard values, epilog), the steps in this section describe what is required for you to produce your interview.

Put the group of questions that gather information for your test environment in your interview class. Remember to implement the getEnvFirstQuestion method to identify the first question of the group.

You must link the last question in the environment group to the rest of the interview (the standard values and epilog). In the getNext() method of the last question of your environment group, use getEnvSuccessorQuestion() to determine the next question in the interview — BasicInterviewParameters provides the rest of the interview.

Finally, you must implement the getEnv() method. The getEnv() method returns a TestEnvironment created from the responses to the questions. The easiest way is to call the interview's export method. The interview's export method calls the export methods for the questions on the current interview path. These questions export their values into a Map object from which you can construct a test environment. For detailed examples see the source code examples in the jt_install\examples directory.

Providing the Resource File for the Interview

In the constructor for your interview class, call:


For example:


This uses a file called (or a localized variant) in the same directory as the interview class. See Creating Question Text and More Info below for more information.

Providing the More Info Help for the Interview

In the constructor for your interview class, call:


For example:


This uses a HelpSet called demotck.hs (or a localized variant) in the moreInfo directory located in the directory that contains the interview class. See Creating Question Text and More Info for more information.

Creating Question Text and More Info

As you saw when you ran the tutorial in Chapter 2, the configuration interview is presented to the user in the configuration editor. The question text and answer controls are presented in the Question pane, and information that helps the user answer the question is presented in the More Info pane.

Figure 6-3 The JavaTest Configuration Editor: Question and More Info Panes

Description of Figure 6-3 follows
Description of "Figure 6-3 The JavaTest Configuration Editor: Question and More Info Panes"

The following sections focus on the text portions of the interview — the question text and the More Info help.

Writing Style

The style that you use for writing question text is very important. Experience has shown that it is very important to make the question text as clear, concise, and unambiguous as you can. Always try to use imperative statements, direct questions, and short explanations. If possible, have a proficient writer edit the questions to ensure readability and consistency.

Only put question text in the question pane. Information that helps the user answer the questions, including examples, should be provided in the More Info pane. The following figure shows a question where examples and other helpful information are included in the question pane with the question text:

Figure 6-4 Question Without More Info Help

Description of Figure 6-4 follows
Description of "Figure 6-4 Question Without More Info Help"

The following example shows how this question can be improved by reorganizing and slightly rewriting the question text and moving the examples and extra information to the More Info pane:

Figure 6-5 Question With More Info Help

Description of Figure 6-5 follows
Description of "Figure 6-5 Question With More Info Help"

There are a number of advantages to using the More Info pane to provide examples and other explanatory information:

  • It allows you to keep the questions simpler. As users become familiar with the interview, they may no longer need the additional information to answer the questions. Displaying the extra information to the More Info pane moves it out of the way.

  • The HTML-based More Info pane offers richer formatting, including: images, fonts, and tables

  • The More Info pane can be scrolled to enable longer discussions and examples

Creating Question Text and Keys

Every interview question has its own unique key. The key is based on a name assigned by you and should uniquely identify the question with the interview. Normally, keys are of the form:


You specify the question_name when you create the question, the interview_class_name is automatically added for you.

Question keys are used to identify question titles and text in resource files. The title of the interview and the title and text for every question in the interview is located in a Java resource file. The file contains the following types of elements:

  • The title of the full interview

  • A title for each question of the form: question_key.smry

  • The text for each question of the form: question_key.text

  • Additional entries for choice items that must be localized

For every interview question you create you must add corresponding .smry and .text entries into the resource file.

The following example shows a fragment of the Demo TCK configuration interview resource file:

title=Demo Interview Configuration Editor
AgentInterview.mapArgs.smry=Agent Map File
AgentInterview.mapArgs.text=Will you use a map file when you run the JavaTest Agent? Name provide a short identifier to name the configuration you are creating here.

You can find the full Demo TCK configuration interview resource file in:


The JavaTest harness uses the standard rules for accessing resource files. You can provide alternate versions for other locales by creating additional files in the same directory as with names of the form: See the Java SE platform resource file specification for more details.

Creating More Info

The JavaTest configuration editor enables architects and technical writers to present supplemental information for every question in the interview in the More Info pane. This information may include background information about the question, and examples and suggestions about how to answer them.

The More Info pane is implemented using an embedded JavaHelp window. The JavaHelp viewer supports HTML 3.2 with some additional extensions. For information about the JavaHelp technology, see:


The JavaHelp libraries required to display More Info help are included in javatest.jar and should not be included separately.

The following procedures describe how to set up the More Info system for your interview and how to add More Info topics as you add questions to the interview.

Set Up the More Info System

Create the directories and files used by the More Info system:

  1. Create a top-level directory called moreInfo

    The moreInfo directory should be located in the same directory as your interview class file(s).

  2. Create directories named default and images in the moreInfo directory

    The default directory contains the default localization. If your test suite is ever localized, the other locales can be added beside the default directory. The images directory contains any images you may use in the More Info help.

  3. Copy the Demo TCK HelpSet file to your moreInfo directory and rename it appropriately (retaining the .hs extension)

    The HelpSet file is the XML file that the JavaHelp libraries look for to find all of the help information that defines the HelpSet. Rename it to reflect the name of your test suite. When you write your interview you specify the path to your HelpSet file.

    The path to the Demo TCK HelpSet file is:

  4. Edit the HelpSet file

    The Demo TCK HelpSet file looks like:

    <?xml version='1.0' encoding='ISO-8859-1' ?>
    <!DOCTYPE helpset
    <helpset version="1.0">
    <!-- title -->
      <title>DemoTCK Configuration Interview - Help</title>
    <!-- maps -->
         <mapref location="default/map.xml"/>

    Edit the contents of the <title> tag to reflect the name of your test suite.

  5. Copy the Demo TCK map file to the default directory

    The JavaHelp map file is an XML file that contains a <mapID> entry for every More Info topic. The JavaHelp system uses it to assign an ID to every HTML file.

  6. Copy the Demo TCK style sheet to the default directory

    Use the CSS, level 1 style sheet from the Demo TCK example for your More Info topics. Feel free to change it to suite your needs.

    The path to the Demo TCK style sheet file is:


Create HTML Topics for All Interview Questions

For every question in your interview, you should create an HTML topic file and add an entry for that topic in the map file. The following steps describe how to do both:

  1. Create a map entry for the More Info topic

    Every More Info topic file must have a corresponding <mapID> entry in the map.xml file. The JavaHelp system uses the IDs created in these files. The target attribute defines the ID, and the url attribute defines the path to HTML topic file (relative to the map file). The following example shows the map file for the Demo TCK test suite that you copied to your interview in a previous step.

    <?xml version='1.0' encoding='ISO-8859-1' ?>
    <!DOCTYPE map
      PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
    <map version="1.0">
    <!-- More Info IDs -->
        <mapID target="DemoTCKParameters.cmd Type"            url="cmdType.html" />
        <mapID target="DemoTCKParameters.testVerboseLevel"    url="testVerboseLevel.html" /> 
        <mapID target="DemoTCKParameters.desc"                url="desc.html" />
        <mapID target="DemoTCKParameters.envEnd"              url="envEnd.html" />
        <mapID target="DemoTCKParameters.epilog"              url="epilog.html" />
        <mapID target="DemoTCKParameters.jvm"                 url="jvm.html" />
        <mapID target=""                url="name.html" />
        <mapID target="DemoTCKParameters.prolog"              url="prolog.html" />

    Replace the target and url attributes to match your More Info topics. Remove any extra entries and add new entries as required.

  2. Create an HTML More Info topic file in the default directory

    Copy one of the Demo TCK More Info files from:


    and use it as a template. Be sure to include the <link> tag that references the style sheet.

    Experience has shown that it is helpful for the architect to create "stub" files for every question in the interview. These files are later completed by a technical writer and can provide information that the writer can use.

Customizing Standard Question More Info

The JavaTest package includes default versions of the More Info HTML topics that describe the standard interview questions in both Question mode and Quick Set mode. However, should you wish to customize the content for some or all of these questions, you can override the defaults with files of your own. The following steps describe how to substitute your More Info topics for one of the standard interview questions:

  1. Determine the More Info ID for the question

    You will override the More Info ID in your interview HelpSet. To do so, you have to determine the ID name of the standard question.

    1. Open the configuration editor window to the question you wish to override

      Make sure that you establish cursor focus in the question pane.

    2. Press Alt-Shift-D

      This opens the Configuration Editor Details Browser. The More Info ID is listed in the "id" field.

  2. Create a map entry in your map file as described in the previous section with the same name as the More Info ID you found in step 1.

    For example:

    <mapID target="TestsInterview.needTests"   url="my_needTests.html" />

    Note that the URL must contain the path to a file you create and must be included in your interview HelpSet.

  3. Create your custom version of the HTML More Info topic

    Be sure that you create it at the location you specified in the map file URL field.

Creating the JAR File

After you have created your interview, you must package it into a JAR file for inclusion with your test suite. If you include other custom components with your test suite, they can be packaged together with the interview. See The Test Suite JAR File for more information. You can also use the following file as an example:


After you create the JAR file, put it in the test suite's lib directory and add it to the classpath entry in the testsuite.jtt file.