Command-line parameters
You can find the information about parameters that you can use while running tests from the command-line interface (CLI).
HCL OneTest™ Performance supports the usage of CLI to run tests. Based on the operating system where you installed HCL OneTest™ Performance, you can go to the following directory to use CLI:
| Operating system | The default path to the directory |
|---|---|
| Windows® | C:\Program Files\HCL\hclonetest\cmdline |
| Linux™ | /opt/HCL/hclonetest/cmdline |
| Mac | /Application/HCL/hclonetest/cmdline |
After navigating to the directory, you can run the test by using CLI. The CLI supports various parameters. Based on your requirements, you can use those parameters while running tests. You can enter cmdline -help in CLI to view all the supported parameters.
The workspace is locked after you run the tests from CLI. To check the progress of the test or schedule during the run, you can invoke another workspace and open the project through that workspace.
The CLI does not provide a way to specify the secure storage password for encrypted datasets. You must provide the password in HCL OneTest™ Performance and ensure that it is stored and persisted in the test before you run the test that is associated with an encrypted dataset from CLI. See Activating secure storage of dataset passwords.
You must provide the values for certain parameters to run tests from CLI. The minimum parameters that you need to provide are -workspace, -project, and -suite or -schedule, or -configfile. The remaining parameters are optional. For example, if you provide a complete path of a configuration file for the -configfile parameter that contains the values of the parameters for a test or schedule run, then you need not provide values for the -workspace, -project, and -suite or -schedule parameters.
You can refer to the following tables to know the required and optional parameters and its description:
| Parameters | Description |
|---|---|
| -workspace | Enter the complete path of the Eclipse workspace. For
example, |
| -project | Enter the path including the file name of the project relative to the
workspace. For
example, |
| -suite | Enter the path including the file name of the performance test
relative to the project. For
example, Note: You must not use both the
-suite and -schedule
parameters simultaneously in a single command. You can specify multiple tests separated by a colon character (:) to run multiple tests simultaneously. For example,
You can run any or all tests and compound tests that are in a folder by using the wildcard character * enclosed in quotes in different combinations in the command line. cmdline -workspace <workspace_full_path> -project <project_relative_path> -suite "*". For example, you can run the following commands:
|
| -schedule | Enter the path including the file name of the schedule relative to
the project. For
example, Note: You must not use both the
-schedule and -suite
parameters simultaneously in a single command. You can specify multiple schedules separated by a colon character (:) to run schedules simultaneously. For example,
You can run the following command to run the schedule: cmdline -workspace <workspace_full_path> -project <project_relative_path> -schedules "sch1*" For example, cmdline -workspace "workspace" -project "PT1" -schedules "sch1*" |
| -configfile | Enter the complete path to a configuration file that contains the
parameters for a test or
schedule run. For more information about creating a command line config file from HCL OneTest™ Performance, see the Related information section. Note: If you provide a complete path of a
configuration file for the -configfile parameter,
then you need not provide values for the
-workspace, -project,
and -suite parameters. The contents of a default configuration file are as follows: Note: If you are creating a config file manually, the file must be in the
UTF-8 format. You must not use double quotation marks () in the
file even for values that contain spaces. |
| Parameters | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| -compare | Use this parameter along with -exportstatshtml
to export the result in compare mode. The value can be paths to the runs and are relative to the workspace. You must separate the paths by a comma. |
||||||||
| -duration |
Use this parameter to change the duration of the stages in the rate schedule. For
example,
The stage number specified must exist in the rate schedule. You can specify multiple stages separated by semicolon (;). The time
units that you can specify for the duration are as follows:
Note: The -duration parameter
creates a new copy of the rate schedule that contains the specified
number of duration.
|
||||||||
| -eclipsehome | Use this parameter to provide the complete path to the directory that
contains eclipse.exe, if HCL OneTest™ Performance is not
installed in the default location. The default location of eclipse.exe is as
follows:
For
example, |
||||||||
| -execsummary | Use this parameter to export all of the reports for the test run in a
printable format, also known as an executive summary, to the local
computer. You must specify the path to store the executive summary. For
example, |
||||||||
| -execsummaryreport | Use this parameter to export a specific report as an executive
summary for the test run to the local computer. You must specify the ID of the report to export. You must use this parameter along with the -execsummary parameter. For example,
you can specify http to export the
executive summary of an HTTP performance
report. |
||||||||
| -exportlog | Use this parameter to specify the file directory path to store the
exported HTTP test log. For
example, In the -exportlog parameter, you can provide multiple values when running multiple tests. You must use colon (:) to separate the entries of the parameter value. For
example, If there are multiple values for the -suite parameter and a single value for the -exportlog parameter, then the -exportlog parameter generates the appropriate number of test logs by appending 0, 1, 2, and so on. For
example, The preceding command generates the following test logs:
The last test log generated has the same name as that of value of -exportlog parameter. Note: If there are multiple values for the
-suite and -exportlog
parameters, then the number of -suite values
must match with the number of -exportlog
values. Otherwise, the following error message is
displayed: Error, number of -suite and -exportlog entries do not match. |
||||||||
| -exportlogmillis | Use this parameter if you want to view the timestamp of the test logs
in milliseconds. The default value for the -exportlogmillis is set to false. Therefore, the timestamp in the test logs does not contain milliseconds. |
||||||||
| -exportstatreportlist | Use this parameter to specify the IDs of reports that you want to
export in place of the default report. You can provide multiple report IDs separated by a comma. You can navigate to the Preferences of HCL OneTest™ Performance (), and then you can select Show Report IDs checkbox to view the report IDs. You must use the -exportstatreportlist parameter along with the -exportstats or -exportstatshtml parameter. For
example, |
||||||||
| -exportstats | Use this parameter to provide the complete path to a directory that
you can use to store the exported report in a comma-separated values
(CSV) format. For
example, |
||||||||
| -exportstatspattern | Use the -exportstatspattern parameter along with
the -exportstats parameter to specify a pattern
that defines the name of a CSV or JSON file. You can use the following
token to customize the file
name: "{TEST_NAME}{AGENT_NAME}{SPLIT_INDEX}_{TIMESTAMP}_{REPORT_ID}_{EXPORT_TYPE}" For
example, Note: The
-exportstatspattern parameter is only supported
for the command which is run from the command line of HCL OneTest™ Performance. |
||||||||
| -exportstatsformat | Use this parameter to specify a format for the result that you want
to export along with the -exportstats parameter.
You must use at least one of the following arguments with the
-exportstatsformat parameter:
For
example, You can add multiple arguments separated by a comma. For
example, When you want to export both simple and full type of test results in a json or csv format, you can specify json or csv as the arguments in the command. When the test run completes, the test result exports to simple.json and full.json files. For
example, You can select the Command Line checkbox from the product Preferences () when you want to automatically export test results to one of the selected formats after the test run completes. Remember: When you
run the test from CLI, and if you use the
-exportstats parameter, then CLI preferences take
precedence over the Preferences set in the product. Therefore, the
default format of the exported test result is CSV. For example, when you select the Command Line option and Report format to json in the product Preferences, and run the test from CLI by using the -exportstats parameter, then the result is exported to a csv file after the test run is complete. |
||||||||
| -exportstatshtml | Use this parameter to provide the complete path to a directory that
you can use to export web analytic results. For
example, The results are exported to the specified directory. You can analyze the results on a web browser without using HCL OneTest™ Performance. |
||||||||
| -history | Use this parameter when you want to view a record of all events that
occurred during a test or
schedule run. You can use any of the following options:
For
example, You can add multiple arguments separated by a comma to send test logs during the test or schedule run to HCL OneTest™ Performance and the Jaeger UI. For
example, For more information about how to view test logs in the Jaeger UI and HCL OneTest™ Performance, see the Related information section. |
||||||||
| ignoreunhealthytranscations | Use this parameter if you do not want to record the elapsed time for
the unhealthy transactions during the test run. The default value for the ignoreunhealthytranscations parameter is set to false. Therefore, the elapsed time is recorded for unhealthy transactions. Note: The value provided in the
ignoreunhealthytranscations parameter
always take precedence over the Discard time measurements
for unhealthy transactions option set in the product
preferences (). |
||||||||
| -import | Use this parameter to import the project from your local computer to
a workspace and then run the test from the command-line
interface. When you want to run tests that are in a source control system such as Git, you can clone the project resources from the remote repository to your computer. You must use the -import parameter along with the -workspace parameter and use an empty workspace to import test assets. You can use the -import parameter when you do not want to use your existing workspace or the workspace that you cloned from a remote repository. For
example, |
||||||||
| -importzip | Use this parameter to import the project as test assets with
dependencies into your workspace. You can run test assets from the imported zip file, but you must specify the -importzip parameter along with the -schedule or -suite parameters. For
example, |
||||||||
| -labels | Use this parameter to add labels to test results when you run test
assets from CLI. For example,
You can also use the -labels parameter along with the -publish parameter to add labels to a test result when you want to publish test results to HCL OneTest™ Server. You can add multiple labels to a test result separated by a comma. When you run test assets, then the labels that you added are displayed on the Performance Report in HCL OneTest™ Performance.
The Results page of HCL OneTest™ Server displays the label that
you added, in the specific test asset in the following conditions:
Note: If
the value of the -labels parameter contains
double quotation marks (""), for example, "100"
users, then CLI does not accept values for the
parameter. To work around this problem, you must create a command-line config file, and then run the test by using the -configfile parameter. You can also use the CommandLine.exe file to run the command and add labels in a language that might not support Unicode characters on the Windows® operating system. You can locate the CommandLine.exe file in the following location: <installation_directory>\\HCLIMShared\plugins\com.ibm.rational.test.lt.cmdlineexecute<time_stamp> |
||||||||
| - overridermlabels | Use this parameter to perform any of the following actions:
You must have added the Resource Monitoring labels to the Resource Monitoring sources on the Resource Monitoring page in your HCL OneTest™ Server project. You can then use those labels to collect data from the source while running the schedule from CLI. For example, if you have added a label in HCL OneTest™ Server for a
Resource Monitoring source as rm1, then you can run
the following command to collect data from the
source: You can add multiple labels to a schedule separated by a comma to collect data from multiple sources during the schedule run. For
example: If your label for resource monitoring contains a comma (,) then you must replace the single comma with the double comma in the -overridermlabels parameter. For
example, if you have added a label to a Resource Monitoring source
as rm1,test, then you must run the following command
to collect data from source as
follows: |
||||||||
| -overwrite | Use this parameter to determine whether a result file with the same
name is overwritten or not. The default value is false. If the value is set to true, the file is overwritten and retains the same file name. You must use double quotation marks () for values true or false. For
example, |
||||||||
| -plugins | Use this parameter to provide the complete path to the directory that
contains the plugins directory, if HCL OneTest™ Performance is not installed in the default location. The default location of the
plugins directory is as
follows:
For
example, |
||||||||
| -publish |
Use this parameter to publish test results to HCL OneTest™ Server. Remember: Before you use the
publish parameter, you must provide the offline user token of HCL OneTest™ Server by using any of the following
methods:
You can use the following arguments along with the -publish parameter:
The Reports information section on the
Log file displays the names of the report along with its
corresponding URLs in the following conditions:
Remember: If you provide HCL OneTest™ Server and
the project details in the product Preferences () and if you use the -publish
parameter, the server details in CLI take precedence over the
product preferences.
|
||||||||
| -publish_for | Use this parameter to publish the test results based on the
completion status of the tests:
You must use the -publish_for parameter along with the -publish parameter. You can add multiple arguments for the -publish_for parameter separated by a comma. For
example, |
||||||||
| -publishreports | Use this parameter to publish specific test results to HCL OneTest™ Server. The arguments that you can use with the -publishreports parameter are as follows:
You must use the -publishreports parameter along with the -publish parameter. For
example, You
can prefix the -publishreports arguments with
For
example, Note: When you run service tests, you cannot publish
the functional report directly from the CLI to HCL OneTest™ Server. You must publish the functional report by using HCL OneTest™ Performance. For more information about generating and publishing the functional report, see the Related information section. |
||||||||
| -quiet | Use this parameter when you do not want to display the values and
acceptance status of the parameters on the command-line interface. For
example, |
||||||||
| -rate | Use this parameter to specify a rate that you want to achieve for a
workload in the Rate Runner group. For
example, Where, Rate Runner Group1 is the name of the rate runner group that has two stages. The desired rate for the first stage is one iteration per second and the rate for the second stage is three iterations per minute. Notes:
You can specify multiple Rate Runner groups separated by the
semicolon (;). The time units that you can specify for the rate are
as follows:
|
||||||||
| -results | Use this parameter to specify the name of the results file. The default name of the result file is the test or schedule name with a timestamp appended. You must specify a folder name that is relative to the project to store the test results. For
example, |
||||||||
| -stdout | Use this parameter to display the information about the
test or
schedule on CLI. After you run the test or schedule from CLI, the following outputs are displayed to give you the overall information of the test or schedule:
For
example, |
||||||||
| -swapdatasets | Use this parameter to replace the dataset values during a
test or
schedule run. If the test or schedule is associated with the dataset, you can replace the dataset at run time while initiating the run from CLI. You must ensure that both original and new datasets are in the same workspace and have the same column names. You must also include the path to the dataset when you use the -swapdatasets parameter. You must provide the values for the -swapdatasets parameter in the following format: /project_name/ds_path/original_ds.csv:/project_name/ds_path/new_ds.csv For
example, You can swap multiple datasets that are saved in a different project by adding multiple paths to the dataset separated by a semicolon (;). |
||||||||
| -timerange | Use this parameter along with -exportstats and
-exportstatshtml to export test results within
one or more time ranges. The value of the -timerange parameter is the time range that you specify in the schedule. For
example, You must separate time ranges with a comma and use double quotation marks () when there is space in a time range. |
||||||||
| -usercomments |
Use this parameter to add text that you want to display in the user comments row of the report. For
example,
Note: If the value of the
-usercomments parameter contains double
quotation marks (""), for example, test run with
"dataset", then CLI does not accept values for
the parameter.
To work around this problem, you must create a command-line configuration file by using HCL OneTest™ Performance, and then run the test by using the -configfile parameter. You can also use the CommandLine.exe file to run the command and to add comments in a language that might not support Unicode characters on the Windows® operating system. You can locate the CommandLine.exe file in the following location: <installation_directory>\\HCLIMShared\plugins\com.ibm.rational.test.lt.cmdlineexecute<time_stamp> |
||||||||
| -users | Use this parameter to override the default number of virtual users in
the test or
schedule run. For a schedule, the default is the number of users specified in the schedule editor and for a test, the default is one user. The -users parameter creates a new copy of the schedule that contains the specified number of users. For
example, |
||||||||
| -varfile | Use this parameter to specify the complete path to the XML file that contains the variable initialization. | ||||||||
| -vmargs | Use this parameter to specify the Java maximum heap size for the Java
process that controls the command line playback. You must use the -vmargs parameter with the -Xmx argument. For example, when you use -vmargs -Xmx4096m, specifies the maximum heap size as 4Gb. This method is similar to specifying -Xmx4096m in the eclipse.ini file for HCL OneTest™ Performance when playing back the test from the user interface. For
example, |
