Project Hurricane is a command line tool or web-based service for creating and scheduling load tests of HTTP based APIs. This tutorial will primarily cover using the web-based service. A specific command line related section is provided at the end. The tests are defined in JSON format and provide support for many different features:

Sequences of requests
Random selection from possible requests
Properties for defining the test environment
Variables for passing data between requests
Cookies
Custom HTTP headers

This article will guide the reader through the process of creating their first test script and provide examples for each type of script element available for use in their test scripts.

Your First Script

When you first access the Hurricane service you will see the list of previously created test definitions.

Let’s create a new test:

Enter a name for your test in the Name field at the bottom of the page
Click the “Add Test Definition” button

Your test is created using the name you provided and you are redirected to the Edit Test Definition page.

For our first test, we’re just going to fill out the Main Script section. We’ll work with test properties and the initial and maintenance script documents later in this tutorial. Let’s start by adding some boiler plate content to the Main Script document:

{
	"headers": [],
	"steps":
	[
		{
			"name": "",
			"type": "Request",
			"method": "GET"
			"url": "",
			"headers": [],
			"body": null,
			"actions":
			[
			]
		}
	]
}

Let’s look at the top-level sections or our script:

headers - This array allows us to add custom global headers to our script that will be included when making API requests. These will be described later in this tutorial
steps - This array will hold the steps to take when running our test

Our first test will be very simple and make a single API request. Our boilerplate includes the body for a request step. Let’s look at the fields we’ll need to make an API request:

name - The name of this request. This name will help us differentiate between requests as our tests become more complicated
type - Since this is an API request the type is “Request”. Other types of steps are available and described later in this tutorial
method - The type of HTTP request being made. Can be GET, POST, PATCH, PUT, HEAD, or DELETE
url - The complete URL used to make the request. This includes the protocol http/https, server address, path, and any query parameters if needed
body - The body content to send as part of the request if using POST, PATCH, or PUT. This field should be set to null or removed if using any other method
actions - This array will hold actions to perform after the request has completed. Actions will be covered later in this tutorial

Let’s fill out the request fields with a call to a fictional API endpoint that returns “hello world!” when called:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Hello World",
			"type": "Request",
			"method": "GET"
			"url": "http://localhost/hello",
			"headers": [],
			"body": null,
			"actions":
			[
			]
		}
	]
}

Once we’ve made our changes, we need to save the test definition by clicking on the “Save” button at the bottom of the page. You will be returned to the list of Test Definitions where our newly created test is now listed:

For instructions on running your tests, please see How-to → Run a Load Test

Using Test Properties

Test properties allow you to create placeholders in your scripts that get replaced when the test is run. This makes it easy to create tests that can be run against multiple environments such as Dev, QA, or Production without having to change the test definition each time or have separate definitions for each environment.

Properties vs Variables

It's important to understand the differences between properties and variables and how they are used in a test script. The first difference is where the values for properties and variables come from. Property values are provided at test scheduling time, either through specifically providing a value or using the default value defined in the test definition. Variable values are extracted from request responses while the test is running.

The second difference is related to when the placeholders are replaced. Placeholders that reference properties are replaced prior to starting the test as part of the test preparation. This means that the values cannot be changed once the test has started. Variables change dynamically and their placeholders are replaced every time a test step is executed. Variables are also scoped so that each test session has its own copy of a variable and its value. The only exception to this is that variables used in the initial and maintenance scripts are also shared with all test sessions.

Add a Test Property

Let’s add a property to our test that will hold the protocol and server information for our API request. To add a test property:

Click on the “Add” button in the Test Properties section of the Edit Test Definition page. This adds an empty property entry to the page
Provide a name for the property. For this tutorial we’ll use “ServerDomain”. The name will be used as part of the placeholder and can only contain letters, numbers, ‘-', and '_’
Optionally provide a default value to use for this property if a specific value isn’t given during test scheduling. For this tutorial we use our current server address: “http://localhost”
Once added, click the “Save” button at the bottom of the page

Reference a Test Property

To use our new test property, we need to add a reference to it in our test’s main script. A property reference has the format {{propertyname}}. In our example, we change the “url” field of our request to include a reference to the ServerDomain property:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Hello World",
			"type": "Request",
			"method": "GET"
			"url": "{{ServerDomain}}/hello",
			"body": null,
			"actions":
			[
			]
		}
	]
}

Just before the test is run, the {{ServerDomain}} portion of the “url” field will be replaced with the value of our property. In this case the “url” field value would be rewritten to “http://localhost/hello”. If the test was run against a QA environment, the value might be overwritten to “http://myqaserver”. Now our test can be pointed at any number of different servers at run time without having to change the test definition itself.

Not all fields support property and variable reference replacement. To see if a specific field supports this feature, please see the detailed documentation for each type of script element.

Nesting property references is not supported. The results will be indeterminate.

Sending a Request Body

Let’s create a new test definition using our boiler plate content. This time we’re going to send data to an endpoint that will echo back the text that was sent to it:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Echo",
			"type": "Request",
			"method": "POST"
			"url": "{{ServerDomain}}/echo",
			"headers": [],
			"body":
			{
				"text": "My text content"
			},
			"actions":
			[
			]
		}
	]
}

Short Form vs Long Form Body

The example above defines the body content using the short-form. Since the content is in Json format, the content can simply be written as the value of the “body” property. This also has the benefit that the Content-Type header will automatically be added when the test is run. However, if the content being sent isn’t in json format (i.e. XML) the long form must be used. The following script uses the long form to send the same body content:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Echo",
			"type": "Request",
			"method": "POST"
			"url": "{{ServerDomain}}/echo",
			"headers":
			[
				{
					"name": "Content-Type",
					"value": "application/json"
				}
			],
			"body":	"{\r\n\"text\": \"My text content\"\r\n}",
			"actions":
			[
			]
		}
	]
}

Notice how special characters like line returns and quotes are escaped using ‘\'. If the content contains ‘\’ prior to being escaped, the ‘\’ is escaped by doubling up the '\’ to “\\”. Also, notice that the Content-Type header has to be explicitly added to the header section of this request (or could be added to the top-level header property that is inherited by all steps. Another consideration when deciding to use the short vs long form is the use of properties and variable placeholders. If the placeholder is contained in a quoted property name or value, the short form can be used without issue. However, if the placeholder is expected to be replace with structured content and the use of the placeholder is not quoted, the script definition will no longer be valid Json.

Making Multiple Requests

A test case may require making multiple requests. The top level “steps” property of the test definition is an array that can contain any number of test steps that will be executed in the order they appear when the test is run. Let’s combine our previous test definitions together:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Hello World",
			"type": "Request",
			"method": "GET"
			"url": "{{ServerDomain}}/hello",
			"body": null,
			"actions":
			[
			]
		},
        {
			"name": "Echo",
			"type": "Request",
			"method": "POST"
			"url": "{{ServerDomain}}/echo",
			"headers":
			[
				{
					"name": "Content-Type",
					"value": "application/json"
				}
			],
			"body":	"{\r\n\"text\": \"My text content\"\r\n}",
			"actions":
			[
			]
		}
	]
}

When this test is run, each session will make a call to the hello world endpoint followed by a call to the echo endpoint. After the second request returns, the session will start over and run both again until the test ends. Metrics for each request are tracked separately. Using the top-level “steps” array property makes it easy to run multiple requests in order. However, you may want separate groups of requests or other steps together to help organize a complex test. This can be done by using the sequence or random step which will be covered later in the tutorial.

Using Test Variables

Let’s update our test definition to capture the response from the hello world request and pass it to the echo request. First we need to capture the response and place it into a variable. We do this by adding a Json action to our first request:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Hello World",
			"type": "Request",
			"method": "GET"
			"url": "{{ServerDomain}}/hello",
			"body": null,
			"actions":
			[
				{
					"name": "Capture Result",
					"type": "json",
					"extractionPairs":
					[
						{
							"jsonPath": "text",
							"variableName": "myvar"
						}
					]
				}
			]
		},
        {
			"name": "Echo",
			"type": "Request",
			"method": "POST"
			"url": "{{ServerDomain}}/echo",
			"headers":
			[
				{
					"name": "Content-Type",
					"value": "application/json"
				}
			],
			"body":
			{
				"text": "My text content"
			},
			"actions":
			[
			]
		}
	]
}

All actions have these properties:

name - The name of the action
type - The type of the action (json, cookie). For this example, we’re using the json action to capture information from a json formatted response

The json action has an additional property:

extractionPairs - An array of path and variable name pairs that defines which json properties to extract and what variable to store them in
- jsonPath - A dot separated list of json property names to extract
- variableName - The name of the variable to store the value in. This name is then used in a placeholder in later requests

Our hello world endpoint returns a json document with a single property:

{
  "text": "Hello World!"
}

We reference this property in the jsonPath property. We also give our variable a name of “myvar” so we can use it later. Let’s go ahead and update our test definition to use our new variable to send “Hello World!” to the echo endpoint:

{
	"headers": [],
	"steps":
	[
		{
			"name": "Hello World",
			"type": "Request",
			"method": "GET"
			"url": "{{ServerDomain}}/hello",
			"body": null,
			"actions":
			[
				{
					"name": "Capture Result",
					"type": "json",
					"extractionPairs":
					[
						{
							"jsonPath": "text",
							"variableName": "myvar"
						}
					]
				}
			]
		},
        {
			"name": "Echo",
			"type": "Request",
			"method": "POST"
			"url": "{{ServerDomain}}/echo",
			"headers":
			[
				{
					"name": "Content-Type",
					"value": "application/json"
				}
			],
			"body":
			{
				"text": "[[myvar]]"
			},
			"actions":
			[
			]
		}
	]
}

Notice that the format of a variable reference is different from a property in that instead of surrounding the property name with “{{“ and “}}” you use “[[“ and “]]” for variables. When the session runs, it first makes the request to the hello world endpoint and then grabs the value from the “text” property of the response and stores it in the “myvar” variable. When the echo request is made, the placeholder reference “[[myvar]]” is replaced with the value stored in the “myvar” variable; “Hello World!” in our case.

Each time the session starts over, any variables captured during the previous run are removed to ensure nothing is carried over between loops. The only exception to this are variables captured or modified in the Initial and Maintenance scripts. Those variables are shared with all sessions and can only be modified by those scripts. If you attempt to update the value of a global variable within the Main script, and error will be raised.

Create a Load Testing Script