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 likelihood.

Every session has

  1. a descriptive name and
  2. a step definition function

name is an identifier which you can freely choose but it has to be unique within one test case definition.

Within the step definition function the actual steps of a session are defined.


definition.session("new sign up", function(session) {
  session.get("/");"/sign-up", {
    payload: { email: "" }
  // ...

definition.session("guest", function(session) {
  // ...

Session Likelihood

There are two ways to configure the likelihood of a session. It describes how likely a session is going to be picked up by a newly started client.

If you don't specify anything explicitly, we assume that all sessions have an equal weight of 1, so each session is equally likely to be picked up.


You can configure the likelihood of a session to be picked up by weights. A session with weight of 3 is 3 times as likely to be selected compared to a session with weight of 1.

If you do not provide weights, a weight of 1 is assumed for all sessions.

  "new sign up": 3,
  "guest": 1


  • There has to be at least one session with a non-zero weight.
  • The default weight of sessions is 1.


The total sum of all probabilities has to be exactly 100.

  "new sign up": 94.5,
  "guest": 5.5


The step definition function's parameter is used to define session steps. The step definition function will operate on the given argument session.

Despite basic request steps you can implement simple control structures like wait times, conditions or loops:

session.waitUniform(10, 20);
session.times(4, function(context){});
session.if(variableName, comparator, value, function(context){});

To see all available request types check out the request reference.

NOTE: times, if and forEver statements must have at least one sub-step.


To simulate think times of users in a session StormForger provides wait, waitExp and waitUniform functions.

wait allows you to specify a static think time in seconds. To wait exactly 20.5 seconds, use


Static wait times can be used if you know that your API client does wait for a fixed period of time. If you want to simulate human think time behaviour, please check out waitExp.



In the example above, the think time will be an exponential distribution with a mean equal to 23.1 seconds. This means that the think time varies within the probability distribution that describes the time between events.

We recommend to use waitExp for human think times.


To simulate think times of users in a more uniform way, you can use the waitUniform function with a min/max value.

session.waitUniform(10, 20);

The distribution will be uniform in the interval (in the example above) from 10 seconds to 20 seconds.


To model a loop you can use the times function.

session.times(4, function(context){});


For conditional statements StormForger offers the if function.

session.if(variableName, comparator, value, function(context){});

Valid comparators are: =, !=, >, >=, < and <= — for equal, not equal, greater than, greater or equal than, less than and less than or equal.


session.if(session.getVar("myVariable"), ">", 2, function(context) { });
session.if(session.getVar("otherVariable"), "!=", "", function(context) { });


If you need an endless loop you can use the forEver function. The loop will terminate when your defined test duration time is over.


Sophisticated Sessions

For example using data sources, you can do more sophisticated sessions like this:

// create a reference to the uploaded data source
var users = session.ds.loadStructured("authentication/admin_users.csv");

var user = session.ds.pickFrom(users);
var otherUser = session.ds.pickFrom(users);"/contacts/add", {
  headers: {
    "X-AwesomeApp-Token": user.get("api_token"),
    "X-AwesomeApp-Mail": user.get("mail"),
  payload: {
    phone: "+4917" + nonce: session.ds.generate("random_number", { range: [1, 100000] }),

Session random branching

If you need to select a different branch in a more random way, you can use session.chooseByWeight() or session.chooseByProbability(). Branches will be selected based on their weight or probability.

For example (weight):

  [1.0, function(c) { c.get("/choose/1x"); }],
  [1.5, function(c) { c.get("/choose/1.5x"); }],
  [2.0, function(c) { c.get("/choose/2x"); }],

Or probabilities:

  [10, function(c) { c.get("/choose/10-percent"); }],
  [25, function(c) { c.get("/choose/25-percent"); }],
  [65, function(c) { c.get("/choose/65-percent"); }],

Session Options

You can set additional options for a specific session. Available are:

Rate limiting

This will limit the bandwidth of each client for all requests that follow this option. You can specifiy a download rate in kB/s. There is currently no support for request (upload) rate limiting.


session.setOption("rate_limit", {
  rate: 1024

To reset a currently active rate limiting, set rate to the string "unlimited". Subsequent requests won't be rate limited.

TLS Client Certificates

You can use TLS client certificates e.g. for strong authentication with your application.

To specify the certificate, private key and password for private key, you can use the certificate option:

session.setOption("certificate", {
  "cert": session.ds.getRawFile("tls_client_certificate.pem"),
  "key": session.ds.getRawFile("tls_client_key.pem"),
  "key_password": "password",

Note that you have to provide the certificate and private key in PEM-encoded format as data source type raw, see data sources reference.

Subsequent requests for this client will use this certificate for new TLS connections.

Pre-Defined Variables

Each session provides a set of pre-defined variables which you could use e.g. for logging or debugging purposes. Pre-defined variables can be accessed the same way other custom variables are accessed (see Content Extraction).

session.get("/ping?=" + session.getVar("client_id"));

Each session provides the following variables:

  • client_id: An unique ID for each client per session
  • test_run_uid: The unique ID for a test run instance (e.g. FQJpH0sA)
  • test_run_id: A sequenced integer ID scoped per test case
  • test_case_uid: The unique UID for a test case (e.g. 1mkpVJNC)
  • test_case_name: The test case name given by the user (e.g. black_friday_scenario)

Custom Variables defined via Content Extraction have precedence over Pre-Defined variables.

Session Checks (OK/KO criteria)

You can set different counter for assertions or checks on your response data and (if needed) you can cancel sessions based on a criteria.


You can use session.check() to define OK/KO criteria and every match or mismatch will be counted and shown in the reportings.

In the following example will everything with an HTTP status code above 400 counted as KO and everyting else as OK:

session.check("products_check", session.lastHttpStatus(), "<=", 400);

The first parameter is the name of the check, next the first value, the comparator (see all comparators here) and the last value.


You can use assertions with session.assert(). The assertions are almost like the checks. But if the KO criteria matches, the session will be aborted.

Usage example:

session.assert("product_assert", session.lastHttpStatus(), "<=", 400);

This assertion causes a session abort, if the status is (in the example) above 400. Any session abort will be counted and is shown in the reports and any mismatch will be shown as OK.

Session Aborts

Session aborts can be used on different ways and are mainly used to abort a session for a matching criteria. All session aborts will be counted and are shown in the reports.

Abort as session method

You can use session.abort() to abort a session based on a given criteria, for example:

session.get("/token", {
  extraction: {
    jsonpath: {
      "accessToken": "authorization.token",

session.if(session.getVar("accessToken"), "=", "", function(c) {

Abort as request option

You can use abort_on_error as option on your requests to abort the session, if the response HTTP status code is 400 or higher. For example:

session.get("/products", {
  abort_on_error: true

If you want to disable/enable all abort_on_error you have defined in your session, you can use a default setting (see more settings here):

Get started icon

Get Started

New to StormForger?
With these guides you’ll be up and running in no time!

FAQ icon


Already took a look at our FAQs?

Support icon


Are you stuck? Talk to us! We're humans.

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