Installation (Platform)
5 minute read
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 Binary Download:
Linux install command:
# 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/
Windows Binary Download:
PowerShell install command:
[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" }
Then, move stormforge.exe
to a folder defined in your Windows PATH environment variable.
macOS Binary Download:
macOS install command:
# 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/
Homebrew:
brew install thestormforge/tap/stormforge
We provide a container image at registry.stormforge.io/library/stormforge-cli
(for linux/amd64
and linux/arm64
):
docker pull registry.stormforge.io/library/stormforge-cli
We recommend setting the STORMFORGE_TOKEN
environment variable (from auth create -o token
) if you want to use the container image directly.
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 create -o token
on your own machine after logging in (see above):
$ stormforge auth create 'github-action'
sfc_1234567890abcdef.ATq_123456789012345678901234567890A46JOgP_CmbDVWMBVAdgnhw715Lrrum_1234567890_1234567890s123456789012345678901234567890BOxIJd3qBPJBhfSTa_1234567890.12345678901234567890
You can now copy the generated output and pass it as an environment variable STORMFORGE_TOKEN
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
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 or look at our Advenced CLI usage guide to learn how manage bigger test cases or make them parameterizable.