Getting Started with the forge CLI

StormForger provides a command line tool called forge for easy local development of test cases and integration into your CI/CD pipelines. This guides shows how to install it and some common usage examples.

All examples below assume you are working in the organisation acme-inc and with the test case sandbox.

Note: Our CLI is open-source. You can checkout the code at github.com/stormforger/cli and browse released versions including Changelog details at github.com/stormforger/cli/releases.

Installation

To install the forge CLI tool you can use one the following methods:

  • Download the latest released binary for your platform:
    • Linux: curl -LJO https://app.stormforger.com/download/cli/linux
    • macOS: curl -LJO https://app.stormforger.com/download/cli/darwin
    • Windows: curl -LJO https://app.stormforger.com/download/cli/windows
  • In case you are on macOS and using Homebrew you can:

    brew install stormforger/forge/forge
    
  • You can also use our published Docker image stormforger/cli. We will publish the latest tag, so you can do:

    docker pull stormforger/cli
    docker run stormforger/cli
    

Most actions require authentication. So in case you don't have a StormForger account yet, you have to sign up first - no worries, it's free!

To use the forge CLI in your CI/CD pipeline, you only need to do two things:

  1. Install the forge command line tool in your PATH (see above)
  2. Export an API Token via the environment variable STORMFORGER_JWT. Alternatively you can make it available via the $HOME/.stormforger.toml file or via the --jwt flag.

The next section explains how you can obtain an API Token.

Authentication

API access is managed via API Tokens. Once registered at https://app.stormforger.com you can either login with your personal credentials or create a service account with a unique token for your organisations.

Personal Account

The forge login command allows performs an authentication with our API and obtains a personal authentication token.

forge login your-email@example.com

You will be asked for your credentials. On successful authentication your API Token will be written to ~/.stormforger.toml.

When you are done, you can ensure the API Token is valid by sending an authenticated ping request:

$ forge ping
PONG! Authenticated as your-email@example.com

Service Account

Service Accounts are non-personalized API tokens scoped to a single organisation. They can be created at https://app.stormforger.com/organisations where you can Manage Service Accounts per organisation:

Manage Service Accounts

Service Accounts are useful if you plan to integrate the forge CLI into your CI/CD pipeline, since they are linked to an organisation, not a specific user. After creating a new service account, you are shown a token. Copy this token, as it will not be shown again. If you lose this token, you need to invalidate the service account and create a new one.

To use this token in a CI/CD pipeline, pass it in the STORMFORGER_JWT environment variable to the forge CLI.

Again, to verify that your token works, you can use

$ forge ping
PONG! Authenticated as jenkins-7pxxyyzm@noreply.stormforger.com

Creating and updating your Test Case

You can use the forge test-case create subcommand to create a test case in your organisation from a local file. By adding --update the command also updated the test case if it already exists instead of failing with an error.

forge test-case create --update acme-inc/sandbox cases/blackfriday.js

Debugging a Test Case in Validation Mode

Validation Mode 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 runs.

To run a test case in validation mode, you can use the following command:

forge test-case launch acme-inc/sandbox --validate --dump-traffic --test-case-file=cases/blackfriday.js

The command above uses the following flags:

  • --dump-traffic - Enables traffic recording for easier debugging
  • --validate - Enables the session validation mode with exactly one user per session and checks for any requests errors after the test run finished
  • --test-case-file - Update the test case file as part of the launch command - this saves a separate update command invocation

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 forge test-case launch <org>/<test-case> command.

forge test-case launch acme-inc/sandbox

Within a CI/CD environment we recommend at least the --notes or --title argument though. These are useful to note various background information, 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 --test-case-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.

forge test-case launch acme-inc/sandbox --watch \
  --title="CI/CD Test Run ${JOB_ID}" --notes="git: $(git describe --tags)" \
  --test-case-file=./cases/blackfriday.js

Find out more

The forge CLI contains more command to help. Checkout the README in our git repository for more commands or consult the command help output by running forge --help. You can also checkout our GitHub Actions Guide for an example of using the forge CLI in a CI/CD context.

Icon Support Are you stuck? Talk to us! We're humans.
Icon Schedule a demo Schedule a personal, customized demo. We'll show you around and introduce you to StormForger.
Icon Talk to a human To build and run reliable applications is complex – we know. Schedule a call and we’ll figure things out.

We are using cookies to give you the best online experience. If you continue to use this site, you agree to our use of cookies. By declining we will disable all but strictly required cookies. Please see our privacy policy for more details.


Accept Decline