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.

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

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.

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.

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"}
            ]
        }
    }
}