Share this page

# Run scenarios using the CLI tool

This topic describes how to use the Controller command line interface (CLI) tool for scenario run automation.

Note: You can also use the Controller Service CLI to run scenarios. For detail, see Run the Controller Service from the CLI.

In this topic:

## About the CLI tool

The CLI tool enables you to run load test scenarios from the command prompt using a 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

To invoke the CLI tool, run CLIControllerApp.exe, located in the <installdir>\bin. Append arguments as described in Command line format.

The same user name and password that are used to log into the Controller machine are used to run Controller from the CLI.

Tip:

- If you want to use different user credentials, define them in <<installdir>\bin\CLIControllerApp.exe.config in the <appSettings> tag.

- You can generate the Host ID from the command line, by running licgencli.exe.

## Command line format

Use the following format for the command line arguments:

–{Run type} –{File path} –{Post run command} –ResultName {Result file path} –OverrideLgs {File 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. 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 and path (optional) | Define the path to the folder to store the results. Format: -ResultName <result_path>
Override load generators (optional) | Use to replace the load generators in the scenario with the ones specified in a separate .txt file. For details, see Load generators input file. Format: -OverrideLgs <file_path>
Silent mode (optional) | Use to run the scenario with the UI hidden. Format: -SilentMode

## Sample CLI commands

The following are samples of commands for running test automation.

- Running a test using an XML input file:

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

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

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

## XML input file

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

Copy code

    <CLIRun>
      <Groups>
        <Group>
          <Name>{Group Name}</Name>
          <Vusers>{Number of Vusers}</Vusers>
          <Script>
            <Name>{The name of the script}</Name>
            <Path>{Full path leading to the script}</Path>
            <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 named here is defined in the Hosts section of the input file -->
            <HostName>{Name of the host that will be used by the group.}</HostName>
            <HostName>...</HostName>
          </AssignedHosts>
        </Group>
      </Groups>

      <Hosts>
        <Host>
          <Name>{Host Name}</Name>
          <Installation>{Acceptable values for this element are: 'Unix' or 'Windows'.}</Installation>
          <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 are used in the test
- Hosts. A list of all the hosts that are 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. For details, see Script element, below. AssignedHosts. Contains at least one HostName element HostName. Identical to the name of a defined host. For details, see Host element, below.
Script | A script used by a group. Name.The name of the script. Path. The valid path to the *.zip file containing the script files. For JMeter protocol scripts only (mandatory): JMeterPath. A valid path to the JMeter installation. 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. For details, see Group element, above. Name. The name of the host. Installation. UNIX, WINDOWS 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.

## XML input file samples

The following sample shows sample XML input file for JMeter and WebHTTP.

### Sample JMeter XML input file

Copy code

    <CliRun>
        <Groups>
            <Group>
                <Name>JMeter1</Name>
                <Vusers>1</Vusers>
                <Script>
                    <Name>simple_test</Name>
                    <Path>C:\Protocols\JmeterSimple_test\</Path>
                    <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>
                <IsOverFirewall>false</IsOverFirewall>
            </Host>
            <Host>
                <Name>localhost</Name>
                <Installation>Windows</Installation>
                <IsOverFirewall>false</IsOverFirewall>
            </Host>
        </Hosts>
        <Scheduler>
            <Name>Scheduler 1</Name>
            <Data>
                <Duration>120</Duration>
            </Data>
        </Scheduler>
    </CliRun>

### Sample Web HTTP XML input file

The following code shows an XML input file for Web HTTP.

Copy code

    <CliRun>
        <Groups>
            <Group>
                <Name>a1</Name>
                <Vusers>2</Vusers>
                <Script>
                    <Name>kali</Name>
                    <Path>C:\Users\Administrator\Documents\VuGen\Scripts\kali</Path>
                </Script>
                <AssignedHosts>
                    <HostName>localhost</HostName>
                </AssignedHosts>
            </Group>
        </Groups>
        <Hosts>
            <Host>
                <Name>WIN-2AKM2PQEN8J</Name>
                <Installation>Windows</Installation>
                <IsOverFirewall>false</IsOverFirewall>
            </Host>
            <Host>
                <Name>localhost</Name>
                <Installation>Windows</Installation>
                <IsOverFirewall>false</IsOverFirewall>
            </Host>
        </Hosts>
        <Scheduler>
            <Name>Scheduler 1</Name>
            <Data>
                <Duration>120</Duration>
            </Data>
        </Scheduler>
    </CliRun>

## Load generators input file

You can change one or more of the load generators for a scenario run using the -OverrideLgs <file_path> argument. When the argument is used from the command line, the load generators defined for the scenario in Controller are overridden by the ones you specified.

The original scenario is not changed. A copy of the scenario is made for the run, and saved in the user temp folder.

The replacement load generators are defined in a .txt file. Each line must specify the target and replacement load generators, using the host IP numbers in the following format:

<original_host>=<new_host>

For example:

Copy code

    1
    2
    3
    11.222.333.444=55.666.777.888
    00.111.222.456=77.888.999.000

## Guidelines for the CLI tool

This section provides several guidelines to consider when 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. When using the -Run option, dialogs and message boxes that 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 <<installdir>\config folder.

- The following property settings are required for the user account used to run the CLI tool:

  - Password never expires must be selected.
  - User must change password at next logon must not be selected.
- If the application is terminated and an error code is displayed, check the Microsoft documentation for the error code meaning.

## See also

- Run scenarios with wlrun command
- Run the Controller Service from the CLI
- Run scenarios in Controller

https://admhelp.microfocus.com Professional Performance Engineering,VuGen 8942
Tips to improve your search results... OpenText™ Professional Performance Engineering Help Center OpenText™ Professional Performance Engineering Help 26.1-26.3 All View Local Help Center View Online Help Center Version: