PureLoad Runner

PureLoad Logo
PureLoad 6.2
February 2020

Documentation Index

PureLoad Runner

PureLoad Runner is used to run load tests without using the PureLoad Console (graphical user interface). Instead a command line interface or Java based API can be used. This requires that the PureLoad Runner Server is started as well as the Naming, Taskspace and Manager servers.


The Runner command line clients uses the Runner Java API to communicate with the Runner server that drives the test. The Runner server will communicate with the PureLoad Naming, Taskspace and Manager servers controlling the load test:

Runner Clients

Two command line clients are provided:

PureLoad Runner Server

PureLoad Runner Server is a server process that can be used from a Java based client to control a PureLoad load execution, without the need for the PureLoad Console (graphical user interface). Before starting the PureLoad Runner Server you should have Naming, Taskspace and Manager processes started.

Also note that PureLoad Enterprise edition is required to use the PureLoad Runner Server.

The PureLoad Runner Server is started in the same way as other PureLoad Servers. For example on a Linux machine:


% bin/runner-server
15:49:57 INFO  - server started: /
15:49:57 INFO  - Connected to naming server:
15:49:57 INFO  - Runner Server started:
        Type: Runner Server
     Version: PureLoad 6.0
        Host: localhost
  IP Address:
    PNC Port: 1999

In this case the PureLoad Runner Server is listening on host: localhost and port: 1999. This can be controlled by editing bin/pureload.properties (see System Properties).

Use runner-cmd to test that the communication with the server works:

% ./bin/runner-cmd localhost 1999 running

This shows that communication with the PureLoad Runner Server works as expected (the server response "false" means that there is no test currently running).

PureLoad Runner Clients

Two command line clients are provided: PureLoad Runner Continuous Integration ("runner-ci") and PureLoad Runner Command ("runner-cmd").


The Runner Continuous Integration command is typically used for for Continuous Load Test. The command performs the following steps:

  • load PLC file(s)
  • start load test execution
  • save results to a directory

runner-ci connects to a PureLoad runner server on specified host and port. Status and progress information and error messages are written to stdout. Arguments to control what to be reported, results to be saved are limited.

The synopsis are:

  runner-ci [-e <scenario-name>] [-m <max-exec-time>] [-p <props-file>] [-v] <host> <port> <result-dir> <plc-file(s)>


Host and where PureLoad runner server is executing.
Port of PureLoad runner server.
Directory where to save results.
One or more PLC files (separated by space) to be executed.
-e <scenario-name>
Name of scenario to be executed. By default all scenarios in PLC files are executed.
This option can be repeated to execute multiple named scenarios.
-m <max-exec-time>
Max time to execute in minutes. Typically used to set a max time, even if execution time is controlled by distribution in PLC file.
This to avoid endless execution even if a scenario is blocked.
-p <props-file>
Properties to be used. See Runner Properties below.
Verbose. Print debugging messages about progress.


The Runner Command (runner-cmd) is a command line program that can be used to load PLC file, execute load test, check results etc. The command always takes the host name and port as parameters, followed by a command to execute and command specific arguments:

  runner-cmd -xml <host> <port> <command>

Where <host> and <port> is the host name and port of the Runner Server.

Generated output will be in plan text format if not the -xml option is used. The -xml option will generate a simple XML format for all results presented.

To get a list of commands that can be used, the help command is used:

% ./bin/runner-cmd help
Usage: runner-cmd [-xml] <host> <port> <command>
Available commands:
   props <properties file>            Load properties file
   load <PLC file>                    Load PLC file
   import <PLC file>                  Import PLC file
   exportplc <PLC file>               Export to PLC file
   start [scenario(s)]                Start execution
   stop                               Stop execution
   abort                              Abort execution
   progress                           Get execution progress
   dist <factor>                      Distribution parameters factor
   workerdetails                      Show a snapshot of current worker details.
   running                            Check if load test is running
   total [<task path>]                Get total summary
   allsummary <child-flag>            Get all summary results
   summary <task-path> <child-flag>   Get summary results for specified node
   alltimeslot <child-flag>           Get all results for latest timeslot
   timeslot <task path> <child-flag> [<reset slot>] Get results for latest timeslot for specified node
   allmonitor [<resource names>]      Get monitor results
   monitor <collector name> [<resource name(s)>]Get monitor results
   allmonitorslot                     Get all monitor results for latest timeslot
   monitorslot <collector name>       Get monitor results for latest timeslot
   kpi <KPI name>                     Get KPI result for specified name
   allkpis                            Get all KPI results.
   export <file-path>                 Export comparer data
   exportxls <file-path>              Export result data
   report <file-path>                 Generate HTML report
   junit <file-path>                  Generate JUnit XML report
   exportall <file-path>              Export all results
   help [command]                     Show help.

Type 'runner-cmd help <command>' for help on a specific command.

Note that the actual output might differ, since new commands might be added.

To get help about at specific command use "help <command>". For example:
% ./bin/runner-cmd help summary
Usage: runner-cmd [-xml] <host> <port>summary <task-path> <child-flag>

Show summary results for specified result node.
The returned result is a summary of all result since the test was started.

<task-path> is the path to a results node. Such as: 'Scenario0/Sequence0/Task1'

Use <child-flag> 'true' to display results for all child nodes (sequences and tasks).
If 'false' only summary for each executed scenrio is displayed.

Runner Properties

Properties are used to control the execution by the Runner clients. Properties must be defined before a load test is started.
The following shows the defined properties and the default values:

# Poll intervals
# Max time slots (before compacting)
# Logging
# Level (debug, info, error)
# Distribution policy
# exact (Exact Iterations) or follow (Follow Distribution)
# Allow test distribution to be updated during a load test.
# Load execution will be less effective, so only enable if necessary.
# Export column delimiter.
# Export end of line delimiter.
# Export column headers.

PureLoad Runner API

The Runner Java API is a Java API to be used to communicate with the PureLoad Runner Server that drives the test. The PureLoad Runner Server will communicate with the PureLoad Naming, Taskspace and Manager servers controlling the load test.

The PureLoad Runner Client will handle all communication between the client and the PureLoad Runner Server isolating all network details from the API. The protocol is internal, based on Java reflection, using standard TCP.

Using the Runner API

The Runner API is documented in javadoc format and available in the <install-home>/api/runner-api directory.
There is also a simple example Java client program using the Runner API available in <install-home>/examples.

To use the Runner API the following libraries found in <install-home>/lib are required:

These jar-files must be used to compile and run a client program using the Runner API.


Copyright © 2020 PureLoad Software Group AB. All rights reserved.