Running Scenarios using the Command Line Interface (CLI) Tool

This topic describes how to use the CLI tool for scenario run automation.

The CLI tool enables you to run load test scenarios from the command prompt using a LoadRunner scenario (.lrs) file or an XML input file, .

You construct the XML input prior to running scenarios, allowing for fully DevOps-oriented flows including:

  • Pulling scripts from any source control
  • Dynamically allocating Dockerized load generators
  • Running scenarios from any CI tool

Invoking the CLI Tool

  1. Prerequisite: Make sure the user name and password of the admin user that will be used to run Controller are defined in <LoadRunner root>\bin\CLIControllerApp.exe.config in the <appSettings> tag.
  2. Run CLIControllerApp.exe, located in the <LoadRunner root>\bin, appending the arguments as described in Command line format below.

Back to top

Command line format

Use the following format for the command line arguments:

–{Run Type} –{File Path} –{Post Run Command} –{Result Name} –{Result Path}

Arguments Description

Run Type

(Mandatory)

  • InputFile. Use this when the input data for the test is provided in *.xml format. The XML input file must contain the structure described in XML Input File.
  • TestPath. Use this when the test runs with data from an existing *.lrs file

File Path

(Mandatory)

A valid Windows path leading to a file.

  • When Run Type is Inputfile, this file is an *.xml file, in the CLI format. See XML Input File below.
  • When Run Type is TestPath, this file must be an *.lrs file.

Post Run Command

(Mandatory)

Determines what happens when the run finishes.

  • Run. Runs the scenario only.
  • Collate. Runs the scenario. When the scenario finishes running, the results are collated.
  • CollateAndAnalyze. Runs the scenario. When the scenario finishes running, the results are collated and analyzed.

Result Name

(optional)

Denotes where the results of the test should be stored.

Format: ResultName

Result Path

(optional)

The path to the location of the stored test run results.

This argument must always follow the -ResultName argument and must contain a valid folder path.

Format: ResultPath

Back to top

Examples

  • Running a test using an XML input file:

    <LoadRunner root>\bin\CLIControllerApp.exe -InputFile C:\CLI.xml -CollateAndAnalyze -ResultName C:\ControllerResultPath\Res_01

  • Running a test using an existing *.lrs file:

    <LoadRunner root>\bin\CLIControllerApp.exe -TestPath C:\testName.lrs -CollateAndAnalyze -ResultName C:\ControllerResultPath\Res

Back to top

XML Input File

The XML input file contains a CLIRun element which has the following structure:

<?xml version="1.0"?>
-<CLIRun>


	-<Groups>
		-<Group>
			<Name>{Group Name}</Name>
			<Vusers>{Number of Vusers}</Vusers>
			-<Script>
				<ID>{Unique identifier for the script}</ID>
				<Name>{The name of the script}</Name>
				<Path>{Full path leading to the script}</Path>
				<ProtocolType>{The protocol type of the script}</ProtocolType>
					<!--Used only in the case of JMeter Protocol Type scripts-->
				<JMeterPath>{Path to the JMeter of the script}</JMeterPath>
				<JMeterAdditionalPropertiesFilePath>{Path to the file containing additional properties for JMeter}</JMeterAdditionalPropertiesFilePath>
					<!--Used only in the case of JMeter Protocol Type scripts-->
			</Script>
			-<AssignedHosts>
				<!-- NOTE: Make sure that the host defined here is also defined in the Hosts section below-->
				<HostName>{Name of the host that will be used by the group.}</HostName>
				<HostName>...</HostName>
			</AssignedHosts>
		</Group>
	</Groups>

	-<Hosts>
		-<Host>
			<Name>{Host Name}</Name>
			<ID>{Host ID}</ID>
			<Installation>{Acceptable values for this element are: 'Unix' or 'Windows'.}</Installation>
			-<HostPurposes>
				<HostPurpose>{Acceptable values for this element are: 'Controller', 'Data Processor', 'Load Generator'.}</HostPurpose>
			</HostPurposes>
			<State>{Acceptable values for this element are: 'Operational', 'NonOperational', 'Unavailable'.}</State>
			<Location>{Host Location}</Location>
			<IsOverFirewall>{Acceptable values for this element are: 'true' or 'false'.}</IsOverFirewall>
		</Host>
	</Hosts>


	-<Scheduler>
		<Name>{Scheduler Name}</Name>
		-<Data>
			<Duration>{The time the test should run for.(in seconds)}</Duration>
		</Data>
	</Scheduler>

</CLIRun>

The CLIRun element contains 3 sections:

  • Groups. A list of all the groups that will be used in the test
  • Hosts. A list of all the hosts that will be available for the Groups
  • Scheduler. The scheduler details.
Element Description
Group

A group in the list of groups.

  • Name. The name of the group.
  • Vusers. The number of vusers in the group. Positive integer value only.
  • Script. The script used by the group. See Script.
  • AssignedHosts. Contains at least one HostName element
  • HostName. Identical to the name of a host defined in the Hosts section

Script

A script used by a group.

  • Name.The name of the script.
  • ID. The unique identifier for the script. Positive integer values only.
  • Path. The valid path to the *.zip file containing the script files.
  • ProtocolType. The protocol type of the script. Can be: JMETER, GUI, WEB, DB, TULIP, TLS, QTEWB, WINRUNNER, VB-WEB, TESTMODULE, TRUWEB
  • For JMeter protocol scripts only (mandatory):

    • JMeterPath. A valid path to the JMETER of the script

    • JMeterAdditionalPropertiesFilePath. The valid path to the file containing additional properties for JMETER

Host

A host in the lists of hosts, and used by a group.

  • Name. The name of the host.
  • ID. The host ID. Positive integer value only.
  • Installation. UNIX, WINDOWS
  • HostPurposes. Contains at lease one HostPurpose tag.
  • HostPurpose. The purpose of the host: Controller, Data Processor, Load Generator.
  • State. Operational, NonOperational, Unavailable
  • Location. Location of the host.
  • IsOverFirewall. Boolean: TRUE, FALSE.
Scheduler

Determines the duration of the scenario run.

  • Name. The scheduler name.
  • Data. Contains the Duration tag.
  • Duration. The duration (in seconds) of the scenario run. Positive integer value only.

Back to top

XML Input File Samples

JMeter sample

<CliRun>
	<Groups>
		<Group>
			<Name>JMeter1</Name>
			<Vusers>1</Vusers>
			<Script>
				<ID>1</ID>
				<Name>simple_test</Name>
				<Path>C:\Protocols\JmeterSimple_test\simple_test.jmx</Path>
				<ProtocolType>JMeter</ProtocolType>
				<JMeterPath>C:\Protocols\JmeterSimple_test\</JMeterPath>
				<JMeterAdditionalPropertiesFilePath>C:\Protocols\JmeterSimple_test\simple_test.properties</JMeterAdditionalPropertiesFilePath>
			</Script>
			<AssignedHosts>
				<HostName>localhost</HostName>
			</AssignedHosts>
		</Group>
	</Groups>
	<Hosts>
		<Host>
			<Name>WIN-2AKM2PQEN8J</Name>
			<Installation>Windows</Installation>
			<HostPurposes>
				<HostPurpose>Load Generator</HostPurpose
				<HostPurpose>Controller</HostPurpose>
			</HostPurposes>
			<State>Ready</State>
			<Location>Local</Location>
			<ID>1</ID>
			<IsOverFirewall>false</IsOverFirewall>
		</Host>
		<Host>
			<Name>localhost</Name>
			<Installation>Windows</Installation>
			<HostPurposes>
				<HostPurpose>Load Generator</HostPurpose>
			</HostPurposes>
			<State>Down</State>
			<Location>Local</Location>
			<ID>2</ID>
`			<IsOverFirewall>false</IsOverFirewall>
		</Host>
	</Hosts>
	<Scheduler>
		<Name>Scheduler 1</Name>
		<Data>
			<Duration>120</Duration>
		</Data>
	</Scheduler>
</CliRun>

WebHTTP Sample

<CliRun>
	<Groups>
		<Group>
			<Name>a1</Name>
			<Vusers>2</Vusers>
			<Script>
				<ID>1</ID>
				<Name>kali</Name>
				<Path>C:\Users\Administrator\Documents\VuGen\Scripts\kali</Path>
			</Script>
			<ProtocolType>QTWeb</ProtocolType>
			<AssignedHosts>
				<HostName>localhost</HostName>
			</AssignedHosts>
		</Group>
	</Groups>
	<Hosts>
		<Host>
			<Name>WIN-2AKM2PQEN8J</Name>
			<Installation>Windows</Installation>
			<HostPurposes>
				<HostPurpose>Load Generator</HostPurpose>
				<HostPurpose>Controller</HostPurpose>
			</HostPurposes>
			<State>Ready</State>
			<Location>Local</Location>
			<ID>1</ID>
			<IsOverFirewall>false</IsOverFirewall>
		</Host>
		<Host>
			<Name>localhost</Name>
			<Installation>Windows</Installation>
			<HostPurposes>
				<HostPurpose>Load Generator</HostPurpose>
			</HostPurposes>
			<State>Down</State>
			<Location>Local</Location>
			<ID>2</ID>
			<IsOverFirewall>false</IsOverFirewall>
		</Host>
	</Hosts>
	<Scheduler>
		<Name>Scheduler 1</Name>
		<Data>
			<Duration>120</Duration>
		</Data>
	</Scheduler>
</CliRun>

Back to top

Notes about running tests using the CLI tool

When you invoke Controller from the command line, the following applies:

  • Only one instance of Controller can run at a time.

  • The arguments are case sensitive.

  • Controller will always overwrite results.

  • Controller launched through the command line behaves normally except when using the -Run option. Using the -Run option, dialogs and message boxes that usually open and require the user to close them in a usual launch, do not open in a command line launch.

  • Controller's settings are loaded from wlrun7.ini, located in the <LR installation>\config folder (both)

Back to top

See also: