perst

perst is a wrapper around LoaderIO, which can be configured and run in your commandline multiple tests and validates the measureable values like AVG Response Time and AVG Error Rate.

Command Line Options
Configuration files
Big list of configuration options
Configuration Examples
- YAML
- JSON
- JavaScript

Command Line Options

Usage: perst [options]

Basic options:

Switch	Description
-c, –config FILENAME	Use this config file (if argument is used but value is unspecified, defaults to .perstrc)
-d, –dry-run	Runs all test in dry-run mode
-h, –help	Show this help message
-v, –version	Show version number
–ci	Runs this on a CI
–dump-config [FORMAT]	dumps the config to the stdout in given format (yaml, yml, json, js). Default: yaml
-f, –filter PATTERN	filters the task by given regex. The name attribute will be used with the regex
–color	force the output with colors
–no-color	force the output without colors
–list-tasks	lists all available tasks
-s, –silent	silent mode
–stop-on-failure	stops the tasks execution, if a task fails

Configuration files

At the following locations in the root directory and format can be placed the configuration.

The files will be searched in this order. The first match will be used.

package.json { "perst": {...} }
.perstrc yaml
.perstrc.json json
.perstrc.yaml yaml
.perstrc.yml yaml
.perstrc.js javascript
.perstrc.cjs common js
perst.config.js javascript
perst.config.cjs common js

Or you run perst with the command line switch -c.

You can use environment variables in your configuration. Environment variables are only supported in YAML Files. Every environment variable can be written in the format $NAME or ${NAME}. Only existing environment variables will replaced. YAML configuration use YAML Version 1.2 and supports anchors.

Big list of configuration options

`version`

Defines the version of the configuration file.

Required: false
Type: Number
Values: 1
Default: 1

`api`

Defines some api information currently for loader IO.

Required: true
Type: Object

`api.token`

Defines the loader IO API token.

Required: true
Type: String

`api.server`

Defines the loader IO API server url.

Required: false
Type: String
Default: https://api.loader.io

`api.version`

Defines the loader IO API version.

Required: false
Type: String
Values: v2
Default: v2

`app`

Defines some application options.

Required: true
Type: Object

`app.domain`

Defines the domain for load testing. The domain must be defined in loader IO and must be verified.

Required: true
Type: String
Example: https://www.example.de

`tasks`

Defines every task which should be run. This is an object of tasks.

Required: true
Type: Object

`tasks.[name].name`

Defines the name of the task in loader IO. This name will be used to find an existing task to reuse and rerun them. If no task can be found with this name, the task will be created.

Required: true
Type: String

`tasks.[name].type`

Defines the test type for the task. The article Test Types and Understanding the different test types describe detailed information about the test type.

Required: false
Type: String
Values: per-test, per-second, maintain-load
Default: per-second

Task Type “Clients per test” `per-test`

With the “Clients per test” type, you specify the total number of clients to connect to your application over the duration of the test. If you specify 20000 clients for a 20-second test, 1000 clients will connect each second during that test.

Clients per test

Task Type “Clients per second” `per-second`

The “Clients per second” type is similar to “Clients per test”, but instead of specifying the total, you specify the number of clients to start each second. A 20-second test with 1000 clients per second is the same as a 20-second test at 20000 clients per test.

Clients per second

Task Type “Maintain client load” `maintain-load`

This test allows you to specify a from and a to value for clients. If you specify 0 and 10000 here for example, the test will start with 0 clients and increase up to 10000 simultaneous clients by the end of the test.

Maintain client load

`tasks.[name].duration`

Defines the execution duration of the test in seconds.

Required: false
Type: Integer
Values: >= 60
Default: 60

`tasks.[name].clientsStart`

This defines number of clients for the start for the test type Maintain client load. This value will be ignored for all other test types.

Required: false
Type: Integer
Values: >= 0
Default: 0

`tasks.[name].clients`

This defines number of clients, which should be used. I case of the test type Maintain client load, this will be the number of client at the end of the test.

Required: true
Type: Integer
Values: >= 15

`tasks.[name].timeout`

This defines the timeout for one request. This value is in milliseconds.

Required: false
Type: Integer
Values: >= 0
Default: 10000

`tasks.[name].errorThreshold`

This defines the error percentage threshold.

Required: false
Type: Integer
Values: 0 <= x <= 100
Default: 10000

`tasks.[name].notes`

This defines some notes to add to the test.

Required: false
Type: String

`tasks.[name].tags`

This defines some tags to add to the test.

Required: false
Type: Array of String

`tasks.[name].threshold`

This defined the relevant threshold, whether the test should fail or not.

Required: false
Type: Object

`tasks.[name].threshold.avgResponseTime`

This defines the maximum average response time in milliseconds, which is allowed. If the test exceeds this value, the task will fail.

Required: true
Type: Integer
Values: >= 0
Default: 500

`tasks.[name].threshold.avgErrorRate`

This defines the maximum average error rate, which is allowed. If the test exceeds this value, the task will fail.

Required: true
Type: Integer
Values: 0 <= x <= 100
Default: 0

`tasks.[name].requests`

This defines the multiple request options for the test. This property can be defined beside the tasks.[name].request property, but it can also be defined without the tasks.[name].request property. If both properties are defined, the first request is the request, which is defined in the property tasks.[name].request.

Required: true
Type: Array of Object

The descriptions of the object in this array are the same as described in the property tasks.[name].request.

`tasks.[name].request`

This defines the request options for the test. This property can be defined beside the tasks.[name].requests property, but it can also be defined without the tasks.[name].requests property. If both properties are defined, the first request is the request, which is defined in the property tasks.[name].request.

Required: true
Type: Object

`tasks.[name].request.path`

This defines the absolute path for the request. The path can be start with a / or without it. This path will be combined with the property api.domain.

Required: true
Type: String

`tasks.[name].request.type`

This defines method for the request.

Required: false
Type: String
Values: GET, POST, PUT, PATCH, DELETE
Default: GET

`tasks.[name].request.payloadFile`

This defines a URL of a payload file. Detailed information about the payload file can be found in the article Payload Files.

Required: false
Type: Url

`tasks.[name].request.headers`

This defines header values for the request. If you defined this property, you have to declare the header accept-encoding on your own.

Required: false
Type: Object
Default: {'accept-encoding': 'gzip'}

`tasks.[name].request.parameters`

This defines an array with parameters objects. These parameters will be sent in query string or POST body.

Required: false
Type: Array of Object

`tasks.[name].request.parameters[index].name`

This defines the name of the parameter.

Required: true
Type: String

`tasks.[name].request.parameters[index].value`

This defines the name of the parameter.

Required: true
Type: String

`tasks.[name].request.authentication`

This defines options for the authentication.

Required: false
Type: Object

`tasks.[name].request.authentication.type`

This defines the type of the authentication.

Required: false
Type: String
Values: basic
Default: basic

The value basic defines the authentication as HTTP Basic Auth.

`tasks.[name].request.authentication.login`

This defines login or user name for the authentication.

Required: true
Type: String

`tasks.[name].request.authentication.password`

This defines password for the authentication.

Required: true
Type: String

`tasks.[name].request.variables`

This defines variables whose values will be taken from the header. These variables can be used in all following request. You can read more information in the article Variables.

Required: false
Type: Array of Object

`tasks.[name].request.variables[index].name`

This defines the name of the variable for later use.

Required: true
Type: String

`tasks.[name].request.variables[index].property`

This defines the header property name to get the value from the request.

Required: true
Type: String

`tasks.[name].request.variables[index].source`

This defines source of the variables.

Required: false
Type: String
Values: header
Default: header

Configuration Examples

YAML

version: 1
api:
    token:   bb74abe565ec005944ffcbfa846431e1
    server:  https://api.loader.io
    version: v2

app:
    domain: https://www.example.com

tasks:
    tasks1:
        name:         Task 1
        type:         per-second
        duration:     60
        clientsStart: 1
        clients:      25
        timeout:      10000
        notes:        "some notes"
        tags:
            - tag 1
            - tag 2
        threshold:
            avgResponseTime: 500
            avgErrorRate:    0
        request:
            path:        /nuff/narf
            type:        GET
            payloadFile: https://www.example.de/file
            headers:
                accept-encoding: gzip
            parameters:
                -   name:  parameter 1
                    value: value of parameter 1
                -   name:  parameter 2
                    value: value of parameter 2
            authentication:
                type:     basic
                login:    login
                password: password
            variables:
                -   name:     variable 1 name
                    property: variable 1 property
                    source:   variable 1 source
                -   name:     variable 2 name
                    property: variable 2 property
                    source:   variable 2 source
    tasks2:
        name:     Task 2
        duration: 60
        clients:  25
        threshold:
            avgResponseTime: 500
            avgErrorRate:    0
        requests:
            -   path: /nuff/narf
            -   path: /rofl/copoter

JSON

{
    "version": 1,
    "api": {
        "token": "bb74abe565ec005944ffcbfa846431e1",
        "server": "https://api.loader.io",
        "version": "v2"
    },
    "app": {
        "domain": "https://www.example.com"
    },
    "tasks": {
        "tasks1": {
            "name": "Task 1",
            "type": "per-second",
            "duration": 60,
            "clientsStart": 1,
            "clients": 25,
            "timeout": 10000,
            "notes": "some notes",
            "tags": [
                "tag 1",
                "tag 2"
            ],
            "threshold": {
                "avgResponseTime": 500,
                "avgErrorRate": 0
            },
            "request": {
                "path": "/nuff/narf",
                "type": "GET",
                "payloadFile": "https://www.example.de/file",
                "headers": {
                    "accept-encoding": "gzip"
                },
                "parameters": [
                    {
                        "name": "parameter 1",
                        "value": "value of parameter 1"
                    },
                    {
                        "name": "parameter 2",
                        "value": "value of parameter 2"
                    }
                ],
                "authentication": {
                    "type": "basic",
                    "login": "login",
                    "password": "password"
                },
                "variables": [
                    {
                        "name": "variable 1 name",
                        "property": "variable 1 property",
                        "source": "variable 1 source"
                    },
                    {
                        "name": "variable 2 name",
                        "property": "variable 2 property",
                        "source": "variable 2 source"
                    }
                ]
            }
        },
        "tasks2": {
            "name": "Task 2",
            "duration": 60,
            "clients": 25,
            "threshold": {
                "avgResponseTime": 500,
                "avgErrorRate": 0
            },
            "requests": [
                {"path": "/nuff/narf"},
                {"path": "/rofl/copoter"}
            ]
        }
    }
}

JavaScript

export default {
    "version": 1,
    "api": {
        "token": "bb74abe565ec005944ffcbfa846431e1",
        "server": "https://api.loader.io",
        "version": "v2"
    },
    "app": {
        "domain": "https://www.example.com"
    },
    "tasks": {
        "tasks1": {
            "name": "Task 1",
            "type": "per-second",
            "duration": 60,
            "clientsStart": 1,
            "clients": 25,
            "timeout": 10000,
            "notes": "some notes",
            "tags": [
                "tag 1",
                "tag 2"
            ],
            "threshold": {
                "avgResponseTime": 500,
                "avgErrorRate": 50
            },
            "request": {
                "path": "/nuff/narf",
                "type": "GET",
                "payloadFile": "https://www.example.de/file",
                "headers": {
                    "accept-encoding": "gzip"
                },
                "parameters": [
                    {
                        "name": "parameter 1",
                        "value": "value of parameter 1"
                    },
                    {
                        "name": "parameter 2",
                        "value": "value of parameter 2"
                    }
                ],
                "authentication": {
                    "type": "basic",
                    "login": "login",
                    "password": "password"
                },
                "variables": [
                    {
                        "name": "variable 1 name",
                        "property": "variable 1 property",
                        "source": "variable 1 source"
                    },
                    {
                        "name": "variable 2 name",
                        "property": "variable 2 property",
                        "source": "variable 2 source"
                    }
                ]
            }
        },
        "tasks2": {
            "name": "Task 2",
            "duration": 60,
            "clients": 25,
            "threshold": {
                "avgResponseTime": 500,
                "avgErrorRate": 0
            },
            "requests": [
                {"path": "/nuff/narf"},
                {"path": "/rofl/copoter"}
            ]
        }
    }
}

perst

Table of Contents

Command Line Options

Configuration files

Big list of configuration options

version

api

api.token

api.server

api.version

app

app.domain

tasks

tasks.[name].name

tasks.[name].type

Task Type “Clients per test” per-test

Task Type “Clients per second” per-second

Task Type “Maintain client load” maintain-load

tasks.[name].duration

tasks.[name].clientsStart

tasks.[name].clients

tasks.[name].timeout

tasks.[name].errorThreshold

tasks.[name].notes

tasks.[name].tags

tasks.[name].threshold

tasks.[name].threshold.avgResponseTime

tasks.[name].threshold.avgErrorRate

tasks.[name].requests

tasks.[name].request

tasks.[name].request.path

tasks.[name].request.type

tasks.[name].request.payloadFile

tasks.[name].request.headers

tasks.[name].request.parameters

tasks.[name].request.parameters[index].name

tasks.[name].request.parameters[index].value

tasks.[name].request.authentication

tasks.[name].request.authentication.type

tasks.[name].request.authentication.login

tasks.[name].request.authentication.password

tasks.[name].request.variables

tasks.[name].request.variables[index].name

tasks.[name].request.variables[index].property

tasks.[name].request.variables[index].source