Sieger

Sieger is a script used to repeatedly call API endpoints, analyze the memory used during the process, and create a final report consolidating all gathered data.

Installation and Usage

1. Run npm install sieger from inside your project.
2. Create siegeOptions.json in your project's root directory and customize it according to the documentation below.
3. Run sieger from the command line.

Results

After running sieger, you will find all generated results within {current_directory}/sieges/{current_timestamp}. Within that folder, there will be a file for each siege that is named based on the siege's URL.

A GET request that was sieging "auth/userdata" would look like this:

GET-auth-userdata.txt

A POST request that was sieging "auth/login/:userId" would look like this:

POST-auth-login-$userId.txt

These files will be populated by the amount of memory being used by the application every second while performing the siege.

In addition to the files generated for each siege, sieger will also generate a final siege-report.txt. Here is an image that gives an example of how this report will look.

Documentation

Configuration is applied via {project_root_directory}/siegeOptions.json. siegeOptions.json should be a JSON object that contains two values: the siegeData object and the sieges array.

Values followed by * are required!

siegeData

siegeData is an object that contains the following values.

name (string)

Description:

The name of the application you are sieging

Example:

"calculator"
"designer"

baseUrl* (string)

Description:

The base URL of the server you are trying to siege. This excludes the port, any particular routing, and any query parameters.

Example:

"http://127.0.0.1"
"http://my-hosted-server.herokuapp.com"

port (number)

Description:

The port of the server you are trying to siege.

Example:

8081
3000

defaults (object)

Description:

An object containing the following default values: method, contentType, and numberOfAttacks.

method is the default HTTP method used when not specified by a particular siege and otherwise defaults to "GET".

contentType is the default HTTP content-type header used when not specified by a particular siege and otherwise defaults to "application/json".

numberOfAttacks is the default number of times any particular endpoint is pinged and otherwise defaults to 100.

Example:

{
method: "POST",
contentType: "application/json",
numberOfAttacks: 25
}

apiData (object)

Description:

An object that contains API data used to populate the URL parameters and query parameters of particular sieges. The values inside apiData are completely custom since they are dependent on what data needs to be pulled into a siege. For instance, if one of your sieges is supposed to attack auth/login/:userId, sieger will look for apiData.userId to populate that data inside the URL.

Example:

{
token: "8894ajg6794da943b62fd97cccf263a413dcf60b4d82f7ca1a7f45493329409ae58359889", userId: 123456
}

sieges

sieges is an array that contains objects with the following values.

method (string)

Description:

The HTTP method used when attacking the URL. If not supplied, it will attempt to use siegeData.defaults.method and if that does not exist, it will use "GET".

Example:

"POST"
"PUT"

url* (string)

Description:

The URL that is meant to be attacked, excluding query parameters. Any value that is preceded by : will be replaced by the matching data within siegeData.apiData.

Example:

'auth/logout'
"auth/login/:userId" (:userId will be replaced by siegeData.apiData.userId)

queryParameters (object)

Description:

An object of query parameters to be attached to the URL. Values inside this object can be preceded by : in order to trigger a replacement from the matching value found within siegeData.apiData.

Example:

{
userToken: ":token",
username: "Frederick"
}

If we pretend that siegeData.apiData.token is equal to "token12345", then the final query parameter string will look like ?userToken=token12345&username=Frederick.

body (object)

Description:

An object that is sent as the request body. Mostly used for "POST" and "PUT" requests. Much like queryParameters, body supports prefixing values with : in order to trigger a replacement from a matching value found inside siegeData.apiData.

Example:

{ firstName: "Edward",
lastName: "Scissorhands",
userToken: ":token" }