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);"/users/create", {
  tag: "create-user",
  payload: {
    name: "Smith",
    email: "",
    password: "secret"

Request options
You can specify options for each request. Request options are optional and are specified within each request as a hash.

Read on for a full list of all available options.

Request URL parameters using Placeholder

Use :placeholder keywords in the request URL and fill them with the params key in the request options object:

definition.session("get-url-parameters-session", function(session) {
  session.get("/root/:category/:product_id", {
    params: {
      category: "foo",

Mind that we replace category but not product_id. The result is a GET request to /root/foo/:product_id.

Request Options

Payload for POST requests

payload can either be:

  • a string, which is send as plain text
  • or an object (key-value pairs), which is encoded and send as application/x-www-form-urlencoded.

Note that some applications might require an application/json Content-Type header for JSON encoded payloads.


  // as a plain text string
  payload: "payload string"

  // -OR- as application/x-www-form-urlencoded
  payload: {
    email: user.get("email"),
    password: user.get("password"),

  // -OR- as a JSON string
  payload: JSON.stringify({
    productId: article.get("productId"),
    amount: 1


Request Compression

You can request gzip compression for responses. The gzip option will set an Accept-Encoding header to request compressed responses from the server. The default value is false.

Note that the target server has to support that functionality to deliver compressed responses.

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

HTTP Headers

The headers option is used to set HTTP request headers (key-value pairs).

Note that you cannot set headers beginning with X-StormForger-.

Although allowed by RFC 2616 we currently only support unique header names.

  headers: {
    "X-AwesomeApp-Token": user.get("api_token"),
    "X-AwesomeApp-Mail": user.get("mail"),

Tag Requests

The tag option specifies an identifier (tag) that is associated with the request. A tag may consist of letters, numbers, underscores and dashes and has to start with a letter.

Tags can be used when analyzing the test run.

  tag: "logout"

HTTP Basic Authentication

You can use HTTP basic access authentication. The authentication option is providing an HTTP Basic Authentication.

  authentication: {
    username: "tisba",
    password: "letmein",

Response Extraction

The extraction option is a way to tell StormForger to extract parts of the response body (see extraction).

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


Each StormForger client does automatically manage a cookie jar. Cookies sent by the server in responses to requests (via Set-Cookie header) are automatically added, updated and removed.

You can add a cookie to a request using the additional_cookies option. Note that this cookies will only be set for the specific request.

  additional_cookies: [
      name: "csrfToken",
      value: session.getVar("token"),

Response Matching

To check if a certain string is present in the target's response you can use the match option. A nomatch counter will increment for each response that does not include the specified match. The counter will be displayed at the result page of the test run.

  match: "<returncode>2</returncode>"


Set the following option to perform a request with the correct headers for an XHR-Request.

  xhr: true

Will add the X-Requested-With: XMLHttpRequest header to the current request.


When performing a request that require a CORS preflight request you can set the following option that will create a preceeding OPTIONS-Request that includes the correct Access-Control-Request-Method, Access-Control-Request-Headers and Origin-Headers.

session.get("/api/login", {
  cors: { origin: "", tag: "cors-request-tag" }
  • origin is required and has to be a valid Origin-Header according to RFC 6454.
  • tag is optional and will default to either the requests tag-value (if provided, see Tag Requests) or the literal "cors"

Setting Defaults

You can set defaults which will apply to requests like this:

session.defaults.setAuthenciation({ username: "user", password: "letmein" });
session.defaults.setHeader("Host", "");

Note that the following rules apply:

  • defaults apply only for requests following the definition of defaults
  • defaults are passed into sub-contexts (e.g. in case of if, times, etc)
  • defaults can be unset (using session.defaults.unset()). This only unsets defaults for the current context! Defaults will apply again if the sub-context has ended
  • defaults defined in sub-contexts do not apply after the sub-context has ended
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