Running a test or schedule from a command line

If you want to run a test or schedule without opening the product, you can do so by using the command-line interface.

Before you begin

You must have set the Web Reports preferences in the desktop client to view the status of the test run from the command line. For more information, see Accessing reports remotely.

Procedure

  1. Go to the directory that contains cmdline.bat and cmdline.sh files. On Windows operating systems, this directory is typically found as productInstallationDirectory/cmdline, for example, C:\Program Files\HCL\HCLOneTest\cmdline.
  2. 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 -rate RateRunnerGroupName=iterationNumber/duration, iterationNumber/duration -duration Stage1=durationOfStage; Stage2=durationOfStage -exportlog log_full_path -exportstats local_dir_path -exportstatshtml local_dir_path -compare "result_path1, result_path2"-exportstatreportlist stats_list -execsummary local_dir_path-timerange "all, 5 Users, 10 Users"-usercomments "any user comment"

    Note:
    • The workspace is locked after you issue the command. To check the progress of the test or schedule during the run, invoke another workspace and open the project through that workspace.
    • On Linux, the command must start with cmdline.sh.
    • The command line does not provide a way to specify the secure storage password for resource monitoring. You must provide the password in the workbench and ensure that it is stored and persisted in the schedule before you execute the schedule from the command line.
    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 is located at C:\Program Files\HCL\HCLIMShared\plugins.
    -schedule Optional. But, in a command, it is mandatory to use one of the following options:
    • -suite
    • -schedule
    • -aftsuite
    • -servicename
    You must not use the -schedule option along with the other options. The path includes the file name of the schedule to run relative to the project.

    Starting from 9.2.1.1, you can execute multiple schedules simultaneously.

    For example, -schedule sch1:sch2:sch3.

    -suite Optional. But, in a command, it is mandatory to use one of the following options:
    • -suite
    • -schedule
    • -aftsuite
    • -servicename
    You must not use the -suite option along with the other options. The path includes the file name of the suite to run relative to the project.

    Starting from 9.2.1.1, you can execute multiple tests simultaneously.

    For example, -suite test1:test2:test3.

    -importzip To import the project as test assets with dependencies into your workspace, use the -importzip option. This command is available from 9.2.1.1 and later.

    Optional. You can execute test assets from the imported zip file, but you must specify the -importzip option along with the -schedule option, or -suite option.

    For example, -importzip script.zip -schedule sch1:sch2:sch3.

    -varfile Optional. The complete path to the XML file that contains the variable name and value pairs.
    -servicename Optional. But, in a command, it is mandatory to use one of the following options.
    • -suite
    • -schedule
    • -aftsuite
    • -servicename
    You must not use the -servicename option along with the other options. The path includes the file name of the service to run relative to the project. Instead of running a performance test, the specified service is run when it is 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, false, indicates that the new results file is created. If the value is true, the file is overwritten and retains the same file name. Use double quotes for values "true" or "false".
    -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, specify a maximum heap size of 4096m. This method is similar to specifying -Xmx4096m in the eclipse.ini file for the workbench when playing back the test from the user interface.
    -rate Optional. Use this argument to specify a rate that you want to achieve for a workload in the Rate Runner group. For example, -rate"Rate Runner Group 1=1/s, 3/m; Rate Runner Group 2=5/s, 10/s".
    Here, Rate Runner Group 1 is the name of the Rate Runner group that has two stages. The desired rate for the first state is one iteration per second and the rate for the second stage is three iterations per minute.
    Note: The Rate Runner group name must match with the name in the Rate Schedule.
    -duration Optional. Use this argument to specify the duration of the stages in the Rate Schedule.
    For example, -duration"Stage1=10s; Stage2=3m"
    Note: The stage number specified must exist in the Rate Schedule.
    -publish Optional: Use this argument to publish test results to the HCL OneTest™ Server. The parameters that you can use with it are as follows:
    • serverURL#project.name=projectName

      If the project name is not specified, the name of the current project is used.

    • no - Use this option if you do not want to publish test results after the run. This option is useful if the workbench Preferences are set to publish the results, however, you do not want to publish them.
    -publish_for Use this option to publish the test results based on the completion status of the tests:
    • ALL - This is the default option. Use this option to publish test results for any text execution verdict.
    • PASS - Use this option to publish test results for the tests that have passed.
    • FAIL - Use this option to publish test results for the tests that have failed.
    • ERROR - Use this option to publish test results for the tests that included errors.
    • INCONCLUSIVE - Use this option to publish test results for the tests that were inconclusive.

    You can add multiple parameters separated by a comma.

    -exportlog Optional. The complete path to a file to store the exported HTTP test log.
    -exportstats Optional. Use this option only when you want to export reports in comma-separated values (CSV) format, with the file name derived from the report name. This directory can be relative to the project or a directory on your file system.If the -exportstatreportlist option is not specified, the reports specified on the Export Reports page of the Performance Test Report preferences are exported.
    -timerange Optional. Use this option along with -exportstats, -exportstatshtml, and -execsummary to export test results within a one or more time ranges. The value is the time range that you specified in the schedule. For example, "all, 5 Users,10 Users". Separate time ranges with a comma and use double quotation marks when there is space in a time range.
    -exportstatshtml Use -exportstatshtml only when you want to export web analytic results. The results are exported in the specified directory. You can then analyze the results on a web browser without using the test workbench.
    -compare Use this argument along with -exportstatshtml and -execsummary to export the result in the compare mode. The value can be paths to the runs and are relative to the workspace. Separate the paths by a comma.
    -exportstatreportlist Optional. A comma-separated list of report IDs. Use this option along with exportstats or exportstatshtml to list the reports that you want to export in place of the default reports or the reports selected in the Preferences (Window > Preferences > Test > Performance Test Reports > Export Reports).

    To export reports with this option, you must specify the report IDs. You can use the Copy ID to clipboard button that is at Window > Preferences > Test > Performance Test Reports > Export Reports to help you to copy the report IDs list on your command line.

    Select your reports by using the multi-selection (not the check box selection) and click the button. Paste the clipboard content on your command line editor

    -execsummary Use this option to export all of the reports for the test run in a printable format, also known as an executive summary, to the local computer. Specify the path to store the executive summary.
    -execsummaryreport Use this option to export a specific report as an executive summary for the test run to the local computer. Specify the ID of the report to export. For example, to export an HTTP performance report, specify http. You must use this option along with -execsummary. To copy the IDs of the reports, click Window > Preferences > Test > Performance Test Reports > Export Reports and in Select reports to export section, select the reports and click Copy ID to clipboard. You can now paste the IDs on your command line.
    -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 language that might not support Unicode characters, use the CommandLine.exe file to run the command.
    -publishreports To publish test results in HCL OneTest™ Server, you can use the -publishreports option. The parameters that you can use with it are as follows:
    • FUNCTIONAL
    • MOBILE_WEBUI
    • STATS
    • TESTLOG
    For example, -publishreports "STATS, TESTLOG".

    Optional. Prefix with “!” to publish all the reports except the specified one.

    For example, -publishreports "! TESTLOG".

    All the reports except the TESTLOG report publish to HCL OneTest™ Server after executing the command.

    -stdout Use this option to display the information about the test or schedule on the command line.

    After you run a test or schedule from the command line, the following outputs are displayed to give you the overall information of the test or schedule:

    • --VERDICT - The verdict of the test or schedule.
    • --REMOTE_RESULT - The URL of the result published to HCL OneTest™ Server.
    • --REMOTE_RESULT_UI - The URL of the result published to HCL OneTest™ Server and can be opened in a browser to analyze the result.
    • --LOCAL_RESULT - The path of the result saved locally.

    For example, -workspace workspace_full_path -project proj_rel_path -schedule sched_rel_path -publish publish_url -stdout

    To stop the test run, you can open another command prompt window and use one of the following options with the cmdline option:
    Command Description
    -stoprun Optional: Stops the test run after the specified number of seconds. Finally, block is executed and the test log is transferred before stopping the run. You must use the -workspace command and specify the location of the workspace.
    -abandonrun Optional: Stops the test run immediately. You must use the -workspace command and specify the location of the workspace.
    Note: Messages are displayed to indicate when the test or schedule is launched and when it is completed unless you include the -quiet option.

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 is as follows:
workspace=D:\My Workspace
eclipsehome=C:\Program Files\HCL\HCLOneTest
plugins=C:\Program Files\HCL\HCLIMShared\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 further analysis. For more information, see Exporting report counters automatically.

Feedback