JavaTest Harness Architect's Guide, JavaTest Harness 4.4.1 for the Java Platform E20663-02 |
|
Previous |
Next |
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.
This section focuses on the design of the configuration information and how to determine what information is necessary to run your tests suite.
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.
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.
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 MyNetworkTest.java
*@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:
testHost=129.42.1.50 testPort=8080
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.
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.
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. |
|
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
.
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:
command.execute=com.sun.javatest.lib.ExecStdTestOtherJVMCmd 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:
com.sun.javatest.lib.ExecStdTestOtherJVMCmd
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.
C:\
JDK\bin\java.exe
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.
$testExecuteClass
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.
$testExecuteArgs
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.
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:
command.execute=com.sun.javatest.lib.PassiveAgentCommand -host myHost -port 501 com.sun.javatest.lib.ExecStdTestSameJVMCmd $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.
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 |
|
The value of the |
|
The value of the |
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.
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:
jt_install\examples\javatest\simpleTags\src
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:
In a command window make the following your current directory:
jt_install\examples\javatest\interviewDemo\demotck
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.
Choose Configure > New Configuration to start the interview
Follow the directions in the interview. You can also browse the source for the interview at:
jt_install\examples\javatest\interviewDemo\src
Interviews are built from the following classes:
com.sun.javatest.InterviewParameters
The top-level class used to build JavaTest configuration interviews. This class is a special subtype of com.sun.interview.Interview
that 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.
com.sun.interview.Interview
The base interview class. This class is used directly to implement sub-interviews (if any).
com.sun.javatest.interview.BasicInterviewParameters
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
.
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.
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.
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.
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.
Note: 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. |
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 |
---|---|---|
ChoiceArray |
A set of independent boolean choices |
Set of named checkboxes |
Choice |
A set of alternative choices |
Combo box or radio buttons, depending on the number of choices |
Error |
A pseudo question used to present error messages |
Pop-up dialog box |
File |
A single file |
Type-in field with associated file chooser |
FileList |
A set of files |
A list box with an associated file chooser |
Final |
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 |
|
Float |
A floating point value (optional min./max. values) |
Either slider or type-in field depending on the range |
InetAddress |
An IPv4 or IPv6 address |
Either four integer fields, each of value 0 - 255, or a type-in field with a lookup button. |
Int |
An integer value |
Either slider or type-in field depending on the range |
Interview |
A pseudo question used for sub-interviews; see |
For internal use only; never displayed |
List |
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. |
Null |
Expository text; generally used to introduce a set of questions |
Text only; no user input |
Properties |
Enables configuring multiple key-value pairs in a single question. |
|
String |
String information |
Type-in field that optionally includes suggested answers |
StringList |
A list of strings |
A list box |
Tree |
A tree selection |
A tree selection GUI based on JTree |
YesNo |
A convenience choice question for Yes/No answers |
Radio buttons |
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:
command.execute=com.sun.javatest.lib.ExecStdTestOtherJVMCmd 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
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"); setFirstQuestion(qIntro); }
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) }
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 |
---|---|
prolog |
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. |
environment |
The questions you write to gather information for the test environment |
tests |
Allows users to specify sub-branches of test trees as a way of limiting which tests are executed during a test run |
keywords |
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). |
concurrency |
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. |
epilog |
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
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 get
XxxFirstQuestion()
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 get
XxxFirstQuestion()
question of any group you wish to skip so that it directly returns that group's get
XxxSuccessorQuestion()
. 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
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.
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.
In the constructor for your interview class, call:
setResourceBundle(
bundle_name);
For example:
setResourceBundle("i18n");
This uses a file called i18n.properties
(or a localized variant) in the same directory as the interview class. See Creating Question Text and More Info below for more information.
In the constructor for your interview class, call:
setHelpSet(
moreInfo_helpset_name);
For example:
setHelpSet("moreInfo\demotck.hs");
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.
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
The following sections focus on the text portions of the interview — the question text and the More Info help.
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
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:
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
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:
interview_class_name.
question_name
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? DemoInterview.name.smry=Configuration Name DemoInterview.name.text=Please provide a short identifier to name the configuration you are creating here.
You can find the full Demo TCK configuration interview resource file in:
jt_install\examples\javatest\simpleTags\src\i18n.properties
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 i18n.properties
with names of the form: i18n_
locale.properties
. See the Java SE platform resource file specification for more details.
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: http://java.net/projects/javahelp
Note: The JavaHelp libraries required to display More Info help are included injavatest.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.
Create the directories and files used by the More Info system:
Create a top-level directory called moreInfo
The moreInfo
directory should be located in the same directory as your interview class file(s).
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.
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:
jt_install\examples\javatest\simpleTags\src\moreInfo\demotck.hs
Edit the HelpSet file
The Demo TCK HelpSet file looks like:
<?xml version='1.0' encoding='ISO-8859-1' ?> <!DOCTYPE helpset "http://java.sun.com/products/javahelp/helpset_1_0.dtd"> <helpset version="1.0"> <!-- title --> <title>DemoTCK Configuration Interview - Help</title> <!-- maps --> <maps> <mapref location="default/map.xml"/> </maps> </helpset>
Edit the contents of the <title>
tag to reflect the name of your test suite.
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.
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:
jt_install\examples\javatest\simpleTags\src\moreInfo\default\moreInfo.css
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:
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" "http://java.sun.com/products/javahelp/map_1_0.dtd"> <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="DemoTCKParameters.name" url="name.html" /> <mapID target="DemoTCKParameters.prolog" url="prolog.html" /> </map>
Replace the target
and url
attributes to match your More Info topics. Remove any extra entries and add new entries as required.
Create an HTML More Info topic file in the default
directory
Copy one of the Demo TCK More Info files from:
jt_install\examples\javatest\simpleTags\src\moreInfo\default
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.
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:
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.
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.
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.
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:
jt_install\examples\javatest\simpleTags\demotck\lib\jtdemotck.jar
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.