Running a test or schedule from the command line

You can run a test or schedule from the command line outside of the Eclipse workspace and automatically export the results.

Before you begin

Running a test or schedule on Linux requires an X Windows server, even when the test is run from the command line. For more information, see Running tests from the command line on Linux.

If you shell-share IBM® Rational® Test Workbench Web UI Testeror IBM Rational Performance Tester with IBM Rational Test Workbench Mobile Test Edition and run a mobile test, set the mobile test client to passive mode and close the product.

About this task

To monitor the test, you can access the reports from a web browser. See Accessing reports remotely

Note: Command line does not provide a way to specify the secure storage password for resource monitoring. You must provide the password in workbench and ensure that it is stored and persisted in the schedule prior to attempting to execute the schedule from the command line.

Procedure

To run a test or schedule from the command line, go to the directory that contains the cmdline.bat and cmdline.sh files. On Windows operating systems, this directory is typically productInstallationDirectory/cmdline, for example, C:\Program Files\IBM\SDP\cmdline. You can point your automated test scripts to this file to run tests or or schedule.

Issue the following command:

cmdline -workspace workspace_full_path -project proj_rel_path -eclipsehome eclipse_full_path -plugins plugin_full_path -schedule sched_rel_path -suite suite_rel_path -varfile variable_file_full_path -servicename service -serviceargs service_args -configfile file_full_path -results result_file -overwrite {true | false} -quiet -users nn -vmargs JVM_args -exportlog log_full_path -exportstats/-exportstatshtml local_dir_path -exportstatreportlist stats_list -usercomments "any user comment"

If a value contains spaces, enclose the value in quotation marks. To see the online help for this command, while you are in the directory that contains the .bat file, type cmdline -help.

The following table explains each option:

Option	Description
-workspace	Required. The complete path to the Eclipse workspace.
-project	Required. The path, including the file name, of the project relative to the workspace.
-eclipsehome	Required. The complete path to the directory that contains eclipse.exe.
-plugins	Required. The complete path to the folder that contains the plug-ins. Typically, on Windows operating systems this folder location is C:\Program Files\IBM\IBMIMShared\plugins.
-schedule	Optional, but you must specify the -schedule option, the -suite option, or the -servicename option. The path including the file name of the schedule to run relative to the project.
-suite	Optional, but you must specify the -schedule option, the -suite option, or the -servicename option. The path including the file name of the test to run relative to the project.
-varfile	Optional. The complete path to the XML file that contains the variable name and value pairs.
-servicename	Optional, but you must specify the -schedule option, the -suite option, or the -servicename option. The name of the service to run. Instead of running a performance test, the specified service is run when it becomes available.
-serviceargs	Optional. The series of arguments to pass to the service specified by the -servicename option. For example, `-serviceargs "-myserviceparm1 myserviceparm1value"`. The values are in quotation marks because they contain spaces.
-configfile	Optional. The complete path to a file that contains the parameters for a test or schedule run. Each parameter must be on a single line. To create a configuration file, use an editor that does not wrap lines. Any parameters, whether required or optional, can be set in the configuration file. Command line parameters override the values in this file. Note: The file must be in the UTF-8 format. Do not use quotation marks in this file, even for values that contain spaces.
-results	Optional. The name of the results file. The default result file is the test or schedule name with a time stamp appended. Specify a folder name that is relative to the project to store the test results. For example, `-results folder/resultname`.
-overwrite	Optional. Determines whether a results file with the same name is overwritten. The default value, `true`, means that the results file is overwritten.
-quiet	Optional. Turns off any message output from the launcher and returns to the command shell when the run or the attempt is complete.
-users	Optional. Overrides the default number of virtual users in the run. For a schedule, the default is the number of users specified in the schedule editor. For a test, the default is one user. This option creates a new copy of the schedule that contains the specified number of users.
-vmargs	Optional. To specify the Java maximum heap size for the Java process that controls the command line playback, use the `-vmargs` option with the `-Xmx` argument. For example, when you use `-vmargs -Xmx4096m`, you specify a maximum heap size of 4096m. This way is similar to specifying `-Xmx4096m` in the eclipse.ini file for the workbench when playing back the test from the user interface. For a cloud run, specify `-vmargs -Dcloudcostconfirm`. To enable Web Analytics reports when running the test from the command line, use `-vmargs -DltStats=2`.
-exportlog	Optional. The complete path to a file in which to store the exported HTTP test log.
-exportstats or -exportstatshtml	Optional. The complete path to a directory in which to store exported statistical report data. The statistical report data is stored in comma-separated values (CSV) format, with the file name derived from the report name. If the -exportstatreportlist option is not specified, the reports specified on the Export Reports page of the Performance Test Report preferences are exported. Use -exportstatshtml only when you want to export web analytic results. The results are exported in a compressed format to the specified directory. Extract and analyze the results on a web browser without using the test workbench.
-exportstatreportlist	Optional. A comma-separated list of absolute paths to custom report format files (.view files) to use when exporting statistical report data with the -exportstats option. This parameter overrides workspace preferences. For example, `-exportstatreportlist c:/customreport.view,c:/customreport2.view`.
-usercomments	Optional. Add text within double quotation mark to display it in the User Comments row of the report. Note: On Windows, to add comments in a native language that might not support Unicode characters, it is recommended to use the CommandLine.exe file to run the command.

Note:

Messages are displayed to indicate when the test or schedule is launched and when it is completed, unless you include the -quiet option.
Issuing the command locks the workspace. To check the progress of the test or schedule during the run, invoke another workspace and open the project through that workspace.

Example

Note: The configuration file must contain information in option=value pairs. Although paths that contain spaces must be enclosed in quotation marks on the command line, do not enclose spaces in quotation marks in the configuration file. A sample configuration file looks as follows:

workspace=D:\My Workspace
eclipsehome=C:\Program Files\IBM\SDP
plugins=C:\Program Files\IBM\IBMIMShared\plugins
project=myProject
schedule=mySchedule.testsuite

What to do next

After you run the test or schedule, you may want to export the results. For more information, see Exporting report counters automatically.

Feedback