Installation (Platform)

StormForge provides a command line tool called stormforge that can be used to interact with the Performance Testing application for easy local development of test cases and integration into CI/CD pipelines. It can also be used to interact with Optimize Live and Optimize Pro. This guide shows how to install the stormforge CLI and some common usage examples.

Installing the StormForge Command Line Interface

• Linux
• Windows
• macOS
• Docker

# Automatically selects either AMD64 or ARM64 architecture, downloads
# the appropriate binary, then moves it to a location in PATH
{ [ "$(uname -sm)" = "Linux x86_64"  ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_linux_amd64.tar.gz | tar -xz; } ||
{ [ "$(uname -sm)" = "Linux aarch64" ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_linux_arm64.tar.gz | tar -xz; } &&
sudo mv stormforge /usr/local/bin/

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
If ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") { Invoke-WebRequest -Uri "https://downloads.stormforge.io/stormforge-cli/latest/stormforge_windows_amd64.zip" -Outfile "stormforge.zip" }
If ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { Invoke-WebRequest -Uri "https://downloads.stormforge.io/stormforge-cli/latest/stormforge_windows_arm64.zip" -Outfile "stormforge.zip" }
Expand-Archive "stormforge.zip" "." -WarningVariable $w; if ($w.Count -eq 0) { Remove-Item "stormforge.zip" }
# Move-Item "stormforge.exe" "C:\somewhere-in-your-PATH\stormforge.exe"

# Automatically selects either AMD64 or ARM64 architecture, downloads
# the appropriate binary, then moves it to a location in PATH
{ [ "$(uname -sm)" = "Darwin x86_64" ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_darwin_amd64.tar.gz | tar -xz; } ||
{ [ "$(uname -sm)" = "Darwin arm64"  ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_darwin_arm64.tar.gz | tar -xz; } &&
sudo mv stormforge /usr/local/bin/

brew install thestormforge/tap/stormforge

docker pull registry.stormforge.io/library/stormforge-cli

Authentication

API access is managed via API tokens. Once registered at app.stormforge.io, you can either login with your user account or you can register a new authorization token (or machine to machine client) to use the CLI in CI/CD pipelines or other automation scenarios.

User Account

You can login to your StormForge user account via a web-based form:

stormforge login

Alternatively, you can get a one-time use code to enter into a browser from another device:

stormforge login --url

At anytime you can check to see that you can communicate with the API:

stormforge ping

Authorization Tokens

You can also create an authorization token to use in automated workflows. See our GitHub or GitLab guides for an example. To create a token, run stormforge auth new-token on your own machine after logging in (see above):

$ stormforge auth new-token --name github
STORMFORGE_TOKEN=sfc_1234567890abcdef.ATq_123456789012345678901234567890A46JOgP_CmbDVWMBVAdgnhw715Lrrum_1234567890_1234567890s123456789012345678901234567890BOxIJd3qBPJBhfSTa_1234567890.12345678901234567890

You can now copy the generated STORMFORGE_TOKEN and pass it as an environment variable to the stormforge binary and it will be authenticated.

Creating and updating your Test Case

You can use the stormforge create test-case subcommand to create a test case in your organization from a local file. This command performance an upsert operation, so if you specify a test case name that already exists, it will be updated.

stormforge create test-case sandbox --from-file cases/blackfriday.js

For more options and information about creating test cases with the stormforge CLI, see the online help

stormforge create test-case --help

Debugging a Test Case

Launching a Validation Run allows you to ignore the defined arrival phases and run a single user for each defined session. This allows validation that the defined session flow works as expected. Note that randomness is still a factor and random branching may lead to slightly different results between validation.

To launch a Validation Run, you can use the following command:

stormforge create test-run --test-case sandbox --from-file cases/blackfriday.js --validate

The command above uses the following flags:

• --test-case - specifies the test case that should be used for this test run
• --from-file - Update the test case file as part of the launch command - this saves a separate update command invocation
• --validate - Enables the session validation mode with exactly one user per session and checks for any requests errors after the test run finished

For more tips and tricks on debugging test cases, see our dedicated Debugging page.

Running your Test Case

To finally run a test case, you can drop all the additional flags and just use the stormforge create test-run --test-case <test-case> command.

stormforge create test-run --test-case sandbox

Within a CI/CD environment we recommend using --label, --notes or --title to add context to your Test Launch, e.g. the job id or URL, git commit hash or deployed version of the target site. Adding --watch ensure your CI/CD job blocks until the test run finished. Finally --from-file updates the test case as part of the launch command to ensure you are launching the exact version that is seen by your CI/CD system.

stormforge create test-run --test-case sandbox --watch \
  --title="CI/CD Test Run ${JOB_ID}" \
  --notes="git: $(git describe --tags)" \
  --label="git-sha=$(git rev-parse HEAD)" \
  --label="target=staging" \
  --from-file=./cases/blackfriday.js

Building a Test Case with ECMAScript Modules

You can use the CLI to create a test case that imports other JavaScript code using ECMAScript modules. To take advantage of this functionality, the main file of your test case must use the file extension .mjs, and it can import javascript code from other .js files.

// testcase.mjs
definition.setTarget("http://testapp.loadtest.party");

definition.setArrivalPhases([
  {
    duration: 5 * 60,
    rate: 1.0,
  },
]);

definition.setTestOptions({
  cluster: { sizing: "preflight", },
});

import helloWorldScenario from "./exported_modules.js";
definition.session("hello world", helloWorldScenario);

// file: exported_modules.js
function helloWorldScenario(session) {
  session.get("/hello");
}

export default helloWorldScenario;

This example can be built into a new test case with this command:

stormforge create test-case modular-testcase --from-file testcase.mjs

In addition to ECMAScript modules, the CLI also supports defining variables that can be injected on the command line to make test cases more dynamic. For more complete documentation of these features, see the stormforge CLI’s online help pages for “bundling” and the “create test-case” command.

stormforge help bundling
stormforge create test-case --help

Find out more

The stormforge CLI contains more command help. Consult the command help output by running stormforge --help. You can also checkout our GitHub Actions Guide for an example of using the stormforge CLI in a CI/CD context.