This topic explains how to run existing load tests from the command line interface. In this section:

Running Load Tests

You can run existing load test (.lt) files from the Load Test command line interface. The Load Test command line runs a script that specifies which .lt files to open and how to run the test. Invoke the script whenever you want to run the tests.

Creating the Script

Create a plain text file with UTF-8-character encoding and add the commands to run your load test. Your system may create text files using another character encoding standard. If you experience issues running your script, verify that the correct encoding is used. Write your script in the following format:

open <PATH-TO-LT-FILE>
loadtest <OPTIONS> <SCENARIO-NAME>

The loadtest command runs a test suite load test using the specified scenario. Refer to the Load Test Command Reference for details about the available loadtest command options.

Using Variables

You can declare variables that you want to use in the script using the following syntax:

var VariableName1 = VariableValue
var VariableName2 = "Variable Value with Spaces"

You can reassign variables that have been declared earlier in the script:

var VariableName1 = NewVariableValue

Sample Script

Here is a sample script (comments in the script are preceded with a "#" sign):

#
# Using script commands
#
 
var report-home = C:\CONTINUOUS_LOAD_TEST\ENTERPRISE_LOAD_TEST 
var minutes = 1
 
var scenario = "Steady Load"
var base = tests/loadtester/accuracytest/tests 
var category = Accuracy
 
var test-name = 1-Profile-HPS
open ${base}/${test-name}.lt
loadtest -minutes ${minutes} -allReports ${report-home}/%d/${category}/${test-name} ${scenario}

Running the Script

Invoke Load Test from the command line to run the script:

lt.exe -cmd -run <PATH_TO_YOUR_SCRIPT> // WINDOWS 
./loadtest -cmd -run <PATH_TO_YOUR_SCRIPT> // Linux and macOS

The -cmd argument starts Load Test in command line mode. The -run argument executes the specified Load Test script. Both arguments are required to run a script from the command line.

lt.exe -cmd -run <PATH_TO_YOUR_SCRIPT> // WINDOWS 
./loadtest -cmd -run <PATH_TO_YOUR_SCRIPT> // Linux and macOS

Requesting a License Dynamically

When you run Load Test in command line mode, Load Test uses the license configured in the GUI mode by default. You can also dynamically request a license from a Parasoft License Server with the -licenseServer option. Specify the base URL of the License Server and use the -licenseVus option to specify the number of virtual users allowed by the license. Note that HTTP connections are not supported.

Windows

lt.exe -cmd -run <PATH_TO_YOUR_SCRIPT> -licenseServer <BASE_URL> -licenseUsername username -licensePassword password -licenseVus <INTEGER>

Linux and macOS

./loadtest -cmd -run <PATH_TO_YOUR_SCRIPT> -licenseServer <BASE_URL> -licenseUsername username -licensePassword password -licenseVus <INTEGER>

Examples

Request a 100-VU Load Test license using authentication and an encoded password

-licenseServer https://licenseserver.mydomain.com -licenseUsername username -licensePassword abc0123456789def -licenseVus 100

Request an Unlimited VU Load Test license using authentication with literal password

-licenseServer https://licenseserver.mydomain.com:8443 -licenseUsername username -licensePassword password -licenseVus Unlimited

Request a basic 5-VU Load Test license without authentication

-licenseServer https://licenseserver.mydomain.com:8443

Running Load Test on Remote Machines

You can run load tests on a remote machine from the command line by starting the remote instance of Load Test in server mode and running a project with the local instance of Load Test that is configured to run the tests on the remote server.

Starting Load Test in Server Mode

Use the -loadtestserver flag and specify the port number to enable the Load Test to run remotely. The port number is the local machine's port on which the server is listening. If no port is specified, the default port of 8189 is used.

Windows

lt -loadtestserver [PORT]

Linux and macOS

./loadtest -loadtestserver [PORT]

Configuring a Remote Project

See Running Load Tests on Remote Machines for instructions.

Working with Load Test Machines Located on Different Networks

The machine that runs in GUI mode and provides the interface for controlling the load test is the Load Test controller machine. The controller can communicate with a Load Test server machine located on a different network if the network equipment that bridges these networks allows communication on the port that the Load Test server machine is listening on.

For example, if you run your Load Test controller on network A and your Load Test server is started on port 10095 by an lt -loadtestserver 10095 command on network B, the communication on port 10095 between networks A and B must not restricted by your network equipment. Allow any TCP traffic exchange for that port. Talk to your system or network administrator about the network configuration issues.

Load Test Command Reference

The following commands allow you to start the Load Test Server and run load tests:

Load Test Command Line Options

Use these commands in either the Windows Command Prompt or a Linux shell.

Option	Description
`-cmd`	Starts Load Test in command line mode. Required to run Load Test locally.
`-run`	Specifies the Load Test script to run. Required to run Load Test locally.
`-help`	Shows help information. Does not run testing.
`-licenseServer <BASE_URL>`	Specifies the base URL for the Parasoft License Server. By default, Load Test requests a license from the server configured in the GUI, but this option enables you to dynamically request a license. Optional.
`-licenseUsername <USERNAME>`	Specifies the username associated with the license on the Parasoft License Server. If this argument is not specified, no authentication is used. Optional.
`-licensePassword <PASSWORD/ENCODED_PASSWORD>`	Specifies the password or encoded password associated with the license on the Parasoft License Server. Passwords may be encoded using the `soatestcli -encodepass` command line option. If this argument is not specified, an empty password is used for authentication. Optional.
`-licenseVus <VALUE>`	Specifies the number of virtual users allowed by the license requested from the server specified with the `-licenseServer` option. You can specify an integer value or `unlimited` for unlimited virtual users' licenses.
`-loadtestserver [PORT]`	Starts the Load Test Server on the default port 8189 unless another port is specified. To start the Load Test Server on port 8999, for example, you would specify the port number in the command line argument such as: `lt.exe -loadtestserver 8999`
`-password <LONG_PASSWORD_STRING>`	Specifies a node-locked license to pass to Load Test.
`-J<JVM_OPTION>`	Specifies additional JVM options to pass to the Load Test JVM. (Note that there is no space between the `-J` and the option that follows it). Examples: `lt -J-Xmx4g -J-Xms2g` `lt -J-Dcom.sun.management.jmxremote`

Load Test Script Commands

Command	Option & option arguments	Description
var		Format: `var variable_name = variable_value` Declares a variable name and assigns it a value. Use `${variable_name}` syntax to get the variable value.
open		Format: `open path_to_load_test_project_file` Opens the specified project in Load Test. After a project is loaded, use the `loadtest` command.
loadtest		Format: `loadtest [-settings path_to_local_settings_file] [-env environment_name] [-minutes number] [-vus number \| -hps number]` `[-report` `path_to_report_file] [-html html_directory] [-allReports reportsPath] [-trimReportSeconds headSeconds tailSeconds][trimReportPercentage headPercentage tailPercentage]ScenarioName` Runs a test suite load test using the specified scenario and options. See the rows below for details.
	-settings path_to_local_settings_file	Specifies the path to the settings file, which contains configuration and preferences parameters (see Settings Files).
	-env environment_name	Sets the active environment. Environments are a part of the SOAtest project that are used by the Load Test.
	-minutes number	Specifies the test duration in minutes. If you specify a test duration in this command, it will override the test duration specified in the scenario.
	-vus number	Sets the number of virtual users for each machine in the load test configuration to the given Number. The execution mode is switched to "Weighted Profiles" mode and each machine in the load test configuration is configured to run a steady load with the specified number of virtual users.
	-hps number	Sets the number of hits per second for each machine in the load test configuration to the given Number. The execution mode is switched to "Weighted Profiles" mode and each machine in the load test configuration is configured to run a steady load with the specified number of hits per second.
	-report path_to_report_file	Specifies that you want to create a binary report with the given name
	-html html_directory	Specifies that you want to create an HTML report with the given name in the specified directory.
	-allReports reportsPath	Specifies that you want to create a binary, XML and HTML report under the given directory path.
	-trimReportSeconds headSeconds tailSeconds	Specifies the duration (in seconds) to be trimmed from the beginning and the end of the report*. The seconds values must be non-negative integers. If the sum of the `headSeconds` and `tailSeconds` values is greater than the duration of the report, the trim operation will not be applied.
	-trimReportPercentage headPercentage tailPercentage	Specifies the duration (in a percentage relative to the duration of the report) to be trimmed from the beginning and the end of the report*. The percentages must be non-negative integers. If the sum of the `headPercentage` and `tailPercentage` is equal to or greater than 100, the trim operation will not be applied.

*Load Test report data is collected and saved in approximately three-second intervals. The trimReport commands will discard all report collection points that fall into the specified trim intervals. Because the times of the report collection points and the specified trim values may not match, the actual duration trimmed from the beginning and end of the report may (and in most cases will) exceed the duration specified in the command line. The excess value trimmed from the head and the tail of the report will not exceed the duration of the data collection interval. For more details on how report fragments are saved, see Understanding Report Interval Selection.

Settings Files

Settings files can control various Load Test options. You can create different settings files for different projects, then use the -settings script option to indicate which file should be used for the current command line test.

If a parameter is specified in this file, it will override the related parameter specified in the Load Test preferences. If a parameter is not specified in this file, Load Test will use the parameter specified in the preferences. If there is no relevant parameter in the Load Test preferences, a default value setting will be used.

If you want to use a default setting, remove or comment out the setting from the file. The file contains name/value pairs and uses the following format:

nameString=valueString

Each name/value pair must be on a separate line. Use the hash “#” symbol to comment the name/value entries.

Available Settings

Setting	Description
`echo=true\|false`	If “true” Load Test will echo the settings to the console. Default state is true. If this setting is used, it must be the first entry in the settings file.
`console.log=enable`	Turns on console logging in command line mode. See Console Logging section below. Default is disabled.

Console Logging

Console logging provides load test status information in command line mode as the tests are running. When console logging is enabled (see the console.log=enable setting), the application prints the main load test run time parameters in the console. Load test status is printed in one line every 30 seconds. It contains the following information:

System Time
Percent complete
Run time seconds completed/total
Total tests passed/failed
Average Virtual User count since last log
Average Hit Per Second rate since last log

Example:

2011.04.21 17:54:56 MDT | 53% complete | 32/60 seconds | passed 245/failed 0 | avg. VUs 4 |avg. HPS 8

Page tree

Load Test Command Line Interface - cli