Getting Started

The main test approach with StormForger is to model clients (or users) that will arrive at your system in a given time. Each client that arrives will perform one session and then leaves again – just like in real life.

Anatomy of a Test

Tests consist of one test case, describing the test setup, parameters etc., and test runs, which represent test executions of a test case. This is structured this way to ensure that you can link every test execution to a specific test configuration.

A test case has at least one target which is under test and at least one arrival phase which determines the load progression during your test run. Each client that is launched, will pick one session to execute where a session consists of declarative description of which steps to perform.

The following sections will briefly describe all concepts.


Each test case has to have at least one target. A target specifies the endpoint you want to test, including the host name, port and protocol (http or https). Targets are specified by providing a URL to definition.setTarget:

// or
definition.setTargets(["", ""]);

If you specify a relative URL in your requests, we will use all specified targets in a round robin approach.

Arrival Phases

Arrival Phases specify the load progression of your test. It will determine how many clients will arrive at your targets during the test. You need at least one, but you can have as many phases as you wish.

Every phase has a duration (in seconds) and a rate (in clients per second, can be a float value). Additionally you can specify how many clients are allowed to launch during this phase using max_clients.

    duration: 5 * 60,  // duration in seconds
    rate: 2.5,         // clients to launch per seconds
    max_clients: 100   // optional; launch up to 100 clients in this phase

The sum of all durations will determine the upper bound of your test duration. Your test will end when

  1. no more clients should be launched -AND-
  2. all previously launched clients have completed their session


Each test case has to have at least one session, which describes what a newly launched client will do. Every client that is launched, will pick a session based on its configured probability.

A Session has a descriptive name, a probability (0-100) and a step definition function. name is an identifier, that you can freely choose. The total probability of all sessions has to be exactly 100.

definition.session("hit status api", function(session) {
  // your step definition code goes here.

Step Definition

The step definition function will operate on the given argument session. You can do all kinds of requests, let the client wait a moment, extract content of a response, implement simple control structures like conditions, loops etc.

Making Requests

You can make GET, POST, PUT, PATCH, DELETE and HEAD requests. Each HTTP verb has a corresponding method defined on session: session.get("/path") or"/users/create").

All requests require at least the request path and can have additional options.

session.get("/users/sign_up", requestOptions);

Where requestsOptions are optional. The following options are available:"/path", {
  // Create a payload ...
  // sent as application/x-www-form-urlencoded
  payload: {
    email: "",
    password: "geheim",

  // -OR- as a JSON
  // note that most servers want an
  // application/json Content-Type header
  // to receive JSON
  payload: JSON.stringify({
    productId: "myGreatProduct",
    amount: 1

  // -OR- as a plain string
  payload: "payload string",

  // use gzip compression, default: false
  gzip: true,

  // set arbitrary as needed
  headers: {
    "X-AwesomeApp-Token": "letmein",
    "X-AwesomeApp-Mail": "",

  // tag this request; a tag may consist
  // of letters, numbers, underscores
  // and dashes and has to start with a letter.
  tag: "logout",

  // use HTTP basic access authentication
  authentication: {
    username: "tisba",
    password: "letmein",

  // use response content extraction
  extraction: {
    jsonpath: {
      "accessToken": "authorization.token",