JavaTest Harness Architect's Guide, JavaTest Harness 4.4.1 for the Java Platform E20663-02 |
|
Previous |
Next |
The JavaTest harness provides a number of standard commands that you can use to configure an environment to run a test suite on your test platform. These commands all extend the standard JavaTest Command
class.
With these standard commands, you can configure the JavaTest harness for a wide variety of test platforms. If, however, you find that you cannot create an environment for your test platform using these commands, you may need to write your own: see Writing Custom Commands for more details.
The standard commands are as follows:
ActiveAgentCommand: A command to execute a subcommand on a JavaTest Agent running in active mode
ExecStdTestSameJVMCmd: A command to execute a simple API test in the same JVM in which the JavaTest harness or the JavaTest Agent is running
ExecStdTestOtherJVMCmd: A command to execute a simple API test in a JVM that is separate from the JVM in which the JavaTest harness or the JavaTest Agent is running
JavaCompileCommand: An example command that demonstrates how to invoke a Java application via a wrapper class
PassiveAgentCommand: A command to execute a subcommand on a JavaTest Agent running in passive mode
ProcessCommand: A command to execute a system command in a separate process
SerialAgentCommand: A command to execute a subcommand on a JavaTest Agent, communicating via a serial line
Note: Examples in this appendix use Unix style commands and file separators. |
A command to execute a command in a separate JVM, typically on a remote machine, by delegating it to a JavaTest Agent which has been configured to run in active mode. This means it contacts the JavaTest harness to determine what it should do.
The JavaTest active agent pool must be started before you start running tests that use this command. The active agent pool holds the requests from the active agents until they are required. You can start the active agent pool from the JavaTest GUI or command line.
Usage
com.sun.javatest.agent.ActiveAgentCommand [options] command-class [command-arguments]
Arguments
-classpath path
|
This option allows you to specify a classpath on the system running the JavaTest harness from which to load the command class and any classes it invokes. The classes are automatically loaded into the agent as needed. If the class path is not specified, the classes are loaded from the agent's class path. See Chapter 4 for additional information about using the -classpath option. |
–mapArgs |
The command to be executed might contain values that are specific to the host running the JavaTest harness and that might not be appropriate for the host that actually runs the command. If this option is given, the agent uses a local mapping file to translate specified string values into replacement values. This is typically used to map filenames from the view on one host to the view on another. See the JavaTest online help for more information. |
–tag tag |
This option allows the user to specify a string that is used to identify the request on the agent. If not specified, the default value, command-class, is used. It is suggested that the URL of the test should be used as the value for this option. A configuration can use the symbolic name $testURL , which is substituted when the command is executed. |
command class |
The name of a command class to be executed by the agent. If the -classpath option is not used, the class should be on the classpath of the agent, and should be appropriate for the agent, depending on the security restrictions in effect. For example, an agent running as an application might be able to run a ProcessCommand , but an agent running as an applet might not. The class should implement the interface com.sun.javatest.Command . |
command arguments |
The arguments to be passed to the run method of an instance of the command class running on the agent. The arguments can be translated to agent-specific values if the –mapArgs option is given. |
Description
ActiveAgentCommand
is a facility to execute a command on a JavaTest Agent that has been configured to run in active mode. A JavaTest Agent provides the ability to run tests in a context that might not be able to support the JavaTest harness. This could be because the tests are to be run on a machine with limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which it is not possible to run the JDK.
Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local
on a Solaris platform might be mounted as a network drive like H:
on a Windows platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.
The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.
Any output written by the command when it is executed by the agent appears as the output of the ActiveAgentCommand
command itself. If the command is successfully executed by the agent (i.e. the Command
object is successfully created and the run
method invoked), the result of ActiveAgentCommand
is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.
Example:
Using ActiveAgentCommand to Execute a ProcessCommand on an Active Agent
This example is based on the following sample code demonstrating ProcessCommand
:
com.sun.javatest.lib.ProcessCommand /usr/local/jdk1.6/solaris/bin/javac -classpath /home/juser/classes –d /home/juser/classes HelloTest.java
To make a command execute on another machine, prefix it with ActiveAgentCommand
and any arguments that ActiveAgentCommand
requires:
compile.java=com.sun.javatest.agent.ActiveAgentCommand com.sun.javatest.lib.ProcessCommand \ /usr/local/jdk1.6/solaris/bin/javac \ -classpath /home/juser/classes \ –d /home/juser/classes HelloTest.java
See Also:
All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of ActiveAgentCommand
.
A command that executes a standard test in the same JVM in which JavaTest Agent is running.
Usage
com.sun.javatest.lib.ExecStdTestSameJVMCmd
[options] test_class [test_args]
Arguments
–loadDir directory | Creates a ClassLoader that loads any necessary classes from the specified directory. The ClassLoader is garbage collected once ExecStdTestSameJVMCmd has completed. If you do not specify -loadDir , the system class loader is used. Using a separate ClassLoader for each test reduces the chance that one test interferes with another. Also, using a separate ClassLoader allows the command to unload test classes after the test is executed, which could be critical in memory constrained environments.
On some systems, the security manager restricts the ability to create a |
test class | Specifies the name of the test class to execute. This class must be a subtype of com.sun.javatest.Test . To specify a class in the test description currently being processed by the JavaTest harness, use the $executeClass substitution variable. |
test args | Specifies a list of arguments to be passed to the run method of the class being executed. To specify arguments in the test description currently being processed by the JavaTest harness, use the $executeArgs substitution variable |
Description
ExecStdTestSameJVMCmd
is a JavaTest command that executes a standard test in the same JVM in which the JavaTest Agent is running. The class must be a subtype of com.sun.javatest.Test
.
ExecStdTestSameJVMCmd
creates a new instance of the class, calls its run
method, and passed the class args. If the class is successfully created and invoked, the result of ExecStdTestSameJVMCmd
is equal to the result of the run
method of the object.
Examples:
Simple use of ExecStdTestSameJVMCmd:
command.execute=com.sun.javatest.lib.ExecStdTestSameJVMCmd \ $testExecuteClass $testExecuteArgs
Using ExecStdTestSameJVMCmd Inside an Environment:
com.sun.javatest.lib.ExecStdTestSameJVMCmd HelloTest
See Also:
ExecStdTestOtherJVMCmd
A variant of ProcessCommand
that executes a standard test using a subcommand in a separate process.
Usage
com.sun.javatest.lib.ExecStdTestOtherJVMCmd
[options] [shell variables] subcommand
[args]
Arguments
–v | Used for verbose mode. When ExecStdTestOtherJVMCmd is in verbose mode, additional output information is sent to the TestResult object. |
shell variables | Specifies one or more shell environment values that are required by the sub-command. Shell environment variables are written as: name=value. |
subcommands | Specifies the name of a program that is executed. |
args | Specifies the arguments that are passed to the subcommand. |
Description
ExecStdTestOtherJVMCmd
is a JavaTest command that executes a test with a subcommand in a separate process (using a separate runtime). You would normally use this command to invoke a JVM to run the test class.Examples of subcommands are the compiler for the Java programming language (javac) and the JVM (java). Normally, a test exits by creating a Status object and then invoking its exit method. This command also returns a Status object, which is equal to the object returned by the test.
Examples
Simple Use of ExecStdTestOtherJVMCmd
com.sun.javatest.lib.ExecStdTestOtherJVMCmd \ /usr/local/jdk1.6/solaris/bin/java \ -classpath /home/juser/classes HelloTest
Using ExecStdTestOtherJVMCmd Inside an Environment
command.execute=com.sun.javatest.lib.ExecStdTestOtherJVMCmd \ /usr/local/jdk1.6/solaris/bin/java \ -classpath /home/juser/classes $testExecuteClass $testExecuteArgs
See Also:
ExecStdTestSameJVMCmd
, ProcessCommand
Invokes a compiler in the same JVM in which the JavaTest harness or the JavaTest Agent is running.
Usage
com.sun.javatest.lib.JavaCompileCommand [–compiler compiler-spec] [args]
Arguments
-compiler compiler-spec | If the –compiler option is given, compiler-spec specifies the class name for the compiler, optionally preceded by a name for the compiler followed by a ":". If no compiler name is given before the class name, the default name is "java" followed by a space and then the class name. If the –compiler option is not given, the default value for compiler-spec is javac:sun.tools.javac.Main. |
args | Specifies the arguments to the compiler's compile method. If you use the default compiler, javac, the arguments are exactly the same as those you would use for javac. In this case, you should refer to documentation for the JDK for more details. Otherwise, refer to the documentation for the compiler you specify. |
Description
This command is primarily an example that shows how any application written in the Java programming language can be interfaced to the JavaTest harness by writing a wrapper command. By default, the application in this example is the JDK compiler, javac, but any class implementing the same signature can be invoked. javac is normally run from the command line, per its specification, but it does have an undocumented interface API, that is sufficiently typical to be used as the basis for this example.
The compiler is assumed to have a constructor and compile method matching the following signature:
public class COMPILER { public COMPILER(java.io.OutputStream out, String name); boolean compile(String[] args); }
When JavaCompileCommand
is used, an instance of the compiler is created. The constructor is passed a stream to which to write any messages, and the name of the compiler to be used in those messages. Then, the compile method is called with any args passed to JavaCompileCommand
. If the compile method returns true, the result is a status of "passed"; if it returns false, the result is "failed". If any problems arise, the result is "error".
The source code for this example is provided in the examples directory. It is the file JavaCompileCommand.java
in the directory src/share/classes/com/sun/javatest/lib/
under the main JavaTest installation directory.
Examples:
Simple use of JavaCompileCommand
com.sun.javatest.lib.JavaCompileCommand HelloWorld.java
Using JavaCompileCommand Inside an Environment
command.compile.java=com.sun.javatest.lib.JavaCompileCommand \ –d $testClassDir $testSource
Using JavaCompileCommand to Invoke the RMI compiler
command.compile.java=com.sun.javatest.lib.JavaCompileCommand \ –compiler rmic:sun.rmi.rmic.Main \ –d $testClassDir $testSource
See Also:
ProcessCommand
A command to execute a command on a remote machine by delegating it to a JavaTest Agent that is configured to run in passive mode.
Usage
com.sun.javatest.agent.PassiveAgentCommand
[options] command -class [command-arguments]
Arguments
Description
PassiveAgentCommand
is a facility to execute a command on a JavaTest Agent that has been configured to run in passive mode. A JavaTest Agent provides the ability to run tests in a context that might not be able to support the entire JavaTest harness. Factors that require use of the JavaTest Agent include limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which is not possible to run the JDK.The host and port options identify an agent to be used to execute the command. The JavaTest harness attempts to contact an agent on that system that is running and waiting for requests.
Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local
on a Solaris platform can be mounted as a network drive like H:
on a Windows NT platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.
The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.
Any output written by the command when it is executed by the agent appears as the output of the PassiveAgentCommand
command itself. If the command is successfully executed by the agent (i.e. the Command
object is successfully created and the run
method invoked) then the result of PassiveAgentCommand
is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.
Examples
Using ActiveAgentCommand
to Execute a ProcessCommand
on an Active Agent:
compile.java=\ com.sun.javatest.agent.PassiveAgentCommand –host calloway \ com.sun.javatest.lib.ProcessCommand \ /usr/local/jdk1.6/solaris/bin/javac \ -classpath /home/juser/classes \ –d /home/juser/classes HelloTest.java
See Also:
All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of PassiveAgentCommand
.
Usage
com.sun.javatest.lib.ProcessCommand [options] [envvariables]command [command-arguments]
Arguments
–v | Verbose mode: tracing information is output to the log. |
env variables | This is a list of named values to be passed as environment variables to the command to be executed. Each named value should be written as name=value. |
command | This is the name of the command to be executed in a separate process. |
command arguments | This is a list of arguments to be passed to the command to be executed. |
Description
ProcessCommand
executes a system command in a separate process with the specified set of environment variables and arguments.
The result of the command is a Status object based upon the exit code of the process. An exit code of zero is interpreted as Status.PASSED
; all other exit codes are interpreted as Status.FAILED
. There are variants of ProcessCommand
that provide different interpretations of the exit code. These variants can be used in more specialized circumstances, such as running tests that use exit codes like 95, 96, and 97.
ProcessCommand
copies the standard output stream of the process to the out2 command stream, and the standard error stream of the process to the out1 command stream.
Examples
Simple use of ProcessCommand
com.sun.javatest.lib.ProcessCommand
/usr/local/jdk1.6/solaris/bin/javac
-classpath /home/juser/classes –d /home/juser/classes HelloTest.java
Using ProcessCommand in an Environment
compile.java=com.sun.javatest.lib.ProcessCommand \ /usr/local/jdk1.6/solaris/bin/javac \ -classpath /home/juser/classes \ –d /home/juser/classes $testSource
See Also:
ExecStdTestOtherJVMCmd
A command to execute a command on a remote machine, by delegating it to a JavaTest Agent that has been configured to communicate via a serial RS232 line.
Usage
com.sun.javatest.agent.SerialAgentCommand [options] command-class [command-arguments]
Arguments
Description
SerialAgentCommand
is a facility to execute a command on a JavaTest Agent that has been configured to communicate via a serial line. A JavaTest Agent lets you run tests in a context that might not be able to support all of the JavaTest harness. This might be because the tests are to be run on a machine with limited resources (such as memory), or in a security-restricted environment (such as a browser), or on a newly developed platform on which is not possible to run the JDK.
The port option identifies a serial port on the system running the JavaTest harness, which should be connected to a serial port on the system running the JavaTest Agent. The serial line is accessed via the javax.comm
optional package. This is not part of the standard JDK, and must be added to your class path when you start the JavaTest harness.
Commands often contain host-specific arguments, such as filenames or directories. Although the files and directories might be accessible from the agent host (and in general, should be), the paths might be different. For example, /usr/local
on a Solaris platform could be mounted as a network drive like H:
on a Windows NT platform. When an agent is initialized, it may be given information on how to translate strings from one domain to another. On a per-command basis, the agent can be instructed to translate a command according to the translation tables it is given.
The command to be executed on an agent can be identified with a tag for tracing and debugging purposes. If none is specified, a default identification is used.
Any output written by the command when it is executed by the agent appears as the output of the SerialAgentCommand
command itself. If the command is successfully executed by the agent (i.e. the Command
object is successfully created and the run
method invoked), then the result of SerialAgentCommand
is the result of the command executed by the agent. Otherwise, an appropriate error status is returned.
Examples
This example is based on the following sample code demonstrating ProcessCommand
:
com.sun.javatest.lib.ProcessCommand /usr/local/jdk1.6/solaris/bin/javac -classpath /home/juser/classes –d /home/juser/classes HelloTest.java
A command can be made to execute on another machine simply by prefixing it with SerialAgentCommand
and any arguments that SerialAgentCommand
requires.
compile.java=\ com.sun.javatest.agent.SerialAgentCommand –port ttya \ com.sun.javatest.lib.ProcessCommand \ /usr/local/jdk1.6/solaris/bin/javac -classpath /home/juser/classes –d /home/juser/classes HelloTest.java
See Also:
All the other standard commands in this appendix. Subject to security restrictions on the agent, they can all be executed remotely by means of SerialAgentCommand
.