Loadster Command Line Interface

Loadster is primarily a browser-based tool, but you can use the Loadster CLI to play local scripts and start and run load tests from the command line.

If your scripts exist on your local filesystem as plain old .js files, you can play them with the Loadster CLI. You can even use them in load tests. The script results and test reports will be available in Loadster.

Installing the Loadster CLI

The open source Loadster CLI is available as a self-contained native binary for Windows, Mac, and Linux.

Download the Loadster CLI for Windows, Mac, or Linux

You can store the binary anywhere on your system you want, as long as it’s in your PATH.

Logging In with the Loadster CLI

After you install the Loadster CLI, you can use it to log in to your Loadster account. This basically obtains an auth token for the CLI to use, and the CLI stores it locally in a configuration file so it can communicate with the Loadster API.

$ loadster login
Loadster Username: example@example.com
Loadster Password: ********

If you’re on a shared or untrusted machine and need to remove the local auth token, you can log out afterwards.

$ loadster logout

Otherwise, the CLI maintains a session for quite some time.

Selecting a Project with the Loadster CLI

Most CLI operations, like playing a script or running a load test, require that you’re working in a specific Loadster project.

You can list projects and select one to use.

$ loadster projects list
$ loadster projects use a83sf61

Once you’re “using” a project, script runs and test reports you create from the command line will be stored in that project. You can change to a different project at any time.

Playing Scripts with the Loadster CLI

The Loadster CLI can play scripts that already exist in your Loadster project. It can also play local .js files as Loadster scripts.

If you want to play a script that already exists in your Loadster project (one that you can see and edit from your dashboard within the current project) you can specify its ID.

$ loadster play s63fa11

If you want to play a local protocol script that doesn’t exist in your Loadster dashboard, you can point it at the local file.

$ loadster play --file ./examples/my-protocol-script.js

Playing a local browser script is similar, but you’ll have to specify a bot type in order for the bot to be equipped with a web browser.

$ loadster play --file ./examples/my-browser-script.js --type=browser

When you play a local script, Loadster basically treats the entire file as a code block, so you can use all the special objects available in a code block in your local script.

The CLI blocks while the script runs, and prints realtime script logs like you’d see when playing from the dashboard. It also gives you a link to view the full script run in your browser, in case you want to view screenshots or debug your script further.

Running Tests with the Loadster CLI

The Loadster CLI has two modes for running load tests.

If you start a test, the CLI simply launches the test and exits, providing you with links to view the test report or realtime progress.

If you run a test, the CLI blocks while the test runs, optionally evaluating assertions to pass or fail the load test based on key metrics.

Load Testing with a Scenario Trigger Code

To run a test from a scenario that you’ve created on your Loadster dashboard, you’ll need the scenario’s trigger code. You can get this trigger code by expanding the big launch button on the scenario screen.

You can then start a test by referencing the trigger code.

$ loadster start WsHDupkZEYkSD7bT

Similarly, you can run a test and wait for it to finish with run instead of start.

$ loadster run WsHDupkZEYkSD7bT

Testing with a trigger code is the easiest way to run a scenario that you’ve previously created in your Loadster project.

Load Testing with a Local Script File

If your script files exist on your local filesystem instead of in your Loadster dashboard, you can still use them for load testing.

To do this, you’ll need to specify all the load test options from the command line.

$ loadster start --script=./my-browser-script \
        --type=browser \
        --bots=100 \
        --location="Europe - London" \
        --ramp-up-minutes=3 \
        --ramp-up-pattern=aggressive \
        --peak-minutes=3 \
        --ramp-down-minutes=3 \
        --ramp-down-pattern=linear

Again, you can substitute run for start if you want the Loadster CLI to block and wait until the test finishes.

Generating JSON Output

If you want the CLI to print JSON values instead of human-readable text, you can add the --json flag. This might be helpful if you’re integrating the CLI into your own CI tool or interpreting the test results from a cron job or something.

$ loadster run WsHDupkZEYkSD7bT --json

Labeling the Test

Sometimes it’s helpful to tie a load test back to a specific build number or configuration. You can do this with the --label switch.

$ loadster run WsHDupkZEYkSD7bT --label=ci-build-238-beta

Afterwards, this label will show up on the test report and in your activity feed, so you can easily reference load test results back to the relevant build.

Blocking and Observing Test Status

If you want the CLI to block until the test finishes instead of exiting immediately after starting the test, use the run command instead.

$ loadster run WsHDupkZEYkSD7bT                   # text output
$ loadster run WsHDupkZEYkSD7bT --json            # json output

When you use the run command (instead of the start command), the CLI will keep watching the test progress, and print useful stats every few seconds. For example:

[0:03:25]
 - runningUsers: 175.00
 - responseTimeAverage: 0.25
 - responseTimeP90: 0.71
 - uploadThroughputBytesPerSecond: 2437.50
 - downloadThroughputBytesPerSecond: 190337.25
 - pagesPerSecond: 11.08
 - hitsPerSecond: 32.17
 - totalPages: 2660.00
 - totalHits: 11320.00
 - totalErrors: 1.00
 - totalIterations: 156.00

When the load test finishes, the CLI will exit.

Assertions

The Loadster CLI also supports assertions, so you can evaluate high-level test result metrics against pass-fail criteria. This is useful for automatically failing a build if the performance test results aren’t inline with expectations.

$ loadster run WsHDupkZEYkSD7bT --assert 'totalErrors == 0' --assert 'avgHitsPerSecond >= 24.5'

The example above makes two assertions: the total number of errors in the test must be equal to zero, and the average hits per second throughout the test must be more than 24.5. Assertions are not required, but you can use pretty much as many as you want.

Assertions work on the following metrics:

  • maxUsers
  • avgBytesPerSecond
  • maxBytesPerSecond
  • avgPagesPerSecond
  • maxPagesPerSecond
  • avgHitsPerSecond
  • maxHitsPerSecond
  • totalBytesTransferred
  • totalPages
  • totalHits
  • totalErrors
  • totalIterations

The following operators are supported in assertions:

  • ==
  • <=
  • >=
  • <
  • >

At the end of the test, a breakdown of which assertions passed/failed is printed. If any assertions failed, the process exits with a non-zero status code.

Getting Help with the Loadster CLI

If you’re having trouble with the Loadster CLI, please get in touch! We’re happy to provide support.

You can also check out the Loadster CLI project on GitHub… it’s open source and we welcome contributions.