Installation

In order to install dumpy, run :

npm install -g dumpy

Flow creation

Basic flow

Dumpy allow you to create actions flows with JSON config files.

Imagine we want to use metaweather's API to get London weather forecast, first we need to create dumpyconfig.json with the following content :

{
    "defaults": {
        "base_url": "https://www.metaweather.com/api/"
    }
}

To get London forecasts we need to :

• Get London id (named whoeid in API)
• Use whoeid to get forecast

Override the json file with the following content :

{
    "defaults": {
        "base_url": "https://www.metaweather.com/api/"
    },
    "requests": [
        {
            "url": "location/search/?query=london",
            "store": [
                {
                    "path": "[0].woeid",
                    "to": "londonWoeid"
                }
            ]
        }
    ]
}

We just added a request that GET /search/?query=london and store woeid of first result in a variable named londonWoeid.

Run dumpy with dumpy --config-path <path to your json file> and you will get :

Note : you can use --json-length 0 argument to show full results.

Thanks to the londonWoeid variable we are able to fetch 5 days forecast :

{
    "defaults": {
        "base_url": "https://www.metaweather.com/api/"
    },
    "requests": [
        {
            "url": "location/search/?query=london",
            "store": [
                {
                    "path": "[0].woeid",
                    "to": "londonWoeid"
                }
            ]
        },
        {
            "url": "location/$var(londonWoeid)"
        }
    ]
}

Run again dumpy --json-length 0 and you will get :

Iterate requests

Suppose now we want to get forcast for London, Paris and Berlin, instead of copy paste previous requests we will use options :

{
    "defaults": {
        "base_url": "https://www.metaweather.com/api/"
    },
    "options": [
        {
            "variables": [
                {
                    "name": "city",
                    "value": "london"
                }
            ]
        },
        {
            "variables": [
                {
                    "name": "city",
                    "value": "paris"
                }
            ]
        },
        {
            "variables": [
                {
                    "name": "city",
                    "value": "berlin"
                }
            ]
        }
    ],
    "requests": [
        {
            "url": "location/search/?query=$var(city)",
            "store": [
                {
                    "path": "[0].woeid",
                    "to": "cityWoeid"
                }
            ]
        },
        {
            "url": "location/$var(cityWoeid)"
        }
    ]
}

When options array is specified in config, all requests are performed for each value.

Note that we introduce a new variable city and londonWoeid has been renamed cityWoeid.

If we run dumpy we get :

Structures

Defaults

• base_url (optional) : Base url for requests
• headers (optional) : Default headers for request
• sub (optional) : Array of defaults, requests flow will be iterated over it.
• variables (optional) : Default variables for whole workspace
• inputs (optional) : Prompt variables to user

Requests

There is currently two type of requests: request for HTTP requests and command for shell commands. We specify request's type in type field with one of the above value.

HTTP request

A HTTP request contains the following fields :

• before (optional) : a request to perform before
• after (optional) : a request to perform after
• url : request endpoint
• useBaseUrl (optional) : Default is true. If true, concatenate default`s url with request request's url
• method (optional) : Default is get. Request's HTTP verb
• params (optional) : Query params
• headers (optional) : Request's headers
• data (optional) : Request's body
• store (optional) : Informations about how to store response in variables
• inputs (optional) : Prompt variables to user
• extras (optional) : Can be used by plugins to parse result
• responseExtras (optional) : Can be used by plugins to parse result

Shell command

A shell command contains the following fields :

• data (optional) : Command to perform
• extras (optional) : Can be used by plugins to parse result
• responseExtras (optional) : Can be used by plugins to parse result

Before

before field can be specified at root. It is an object with two fields :

• all (optional) : Array of requests to perform once at start. Defaults variables cannot be used here.
• each (optional) : Array of requests to perform before each request. Variables are availables here.

Inputs

You can prompt user some variables like username, password, ... by using inputs field on requests or defaults, you can hide entries by setting is_secure to true.

Inputs are processed before request.

For example if you want to ask users credentials in before.all :

{
    "before": {
        "all": [{
                "url": "<login endpoint>",
                "method": "post",
                "data": {
                    "username": "$var(username)",
                    "password": "$var(password)"
                },
                "store": [
                    {
                        "path": ".token",
                        "to": "token"
                    }
                ],
                "inputs": [
                    {
                        "description": "What is your username ?",
                        "store_in": "username"
                    },
                    {
                        "description": "What is the password for $var(username) ?",
                        "store_in": "password",
                        "is_secure": true
                    }
                ]
            }
        ]
    },
    "defaults": [...],
    "requests": [...]
}

Variables system

Dumpy has a flexible variables system that allow to make string, number, objects and arrays in absolutely every fields excepted in before.all.

Use $var(<variable name>) for a string variable, $varnum(<variable name>) for a number variable, $varobject(<variable name>) for an array or object variable.

In case of object or array, you can also use variables for childs.

For example :

{
    "defaults": {
        "base_url": "...",
        "variables": [
            {
                "name": "englandCapital",
                "value": "london"
            },
            {
                "name": "deutschlandCapital",
                "value": "berlin"
            },
            {
                "name": "franceCapital",
                "value": "paris"
            },
            {
                "name": "$var(englandCapital)Id",
                "value": 1
            },
            {
                "name": "$var(deutschlandCapital)Id",
                "value": 5
            },
            {
                "name": "$var(franceCapital)Id",
                "value": 8
            },
            {
                "name": "citiesNames",
                "value": ["$var(englandCapital)", "$var(deutschlandCapital)", "$var(franceCapital)"]
            },
            {
                "name": "citiesIds",
                "value": ["$varnum(londonId)", "$varnum(berlinId)", "$varnum(parisId)"]
            },
            {
                "name": "cityBody",
                "value": {
                    "ids": "$varobject(citiesIds)",
                    "names": "$varobject(citiesNames)"
                }
            }
        ]
    },
    "requests": [
        {
            "url": "...",
            "method": "post",
            "data": "$varobject(cityBody)"
        },
    ]
}

Body sent in the request will be :

{
    "ids": [1, 5, 8],
    "names": ["london", "berlin", "paris"]
}

You can nest variables declarations, for example if you replace :

{
    "name": "citiesIds",
    "value": ["$varnum(londonId)", "$varnum(berlinId)", "$varnum(parisId)"]
},

By :

{
    "name": "citiesIds",
    "value": ["$varnum($var(englandCapital)Id)", "$varnum($var(deutschlandCapital)Id)", "$varnum($var(franceCapital)Id)"]
},

It will also work and the same body will be sent.

In this example we used variables for body but you can do the same for headers, store, and so much fields !

Handle responses

You can do what you want with responses by using engines. You can use one of provided engines or create your own.

To use one of our engines you can add --engine <name of engine> argument.

Provided engines

printer

Print every requests and responses in a pretty way. This is the default engine when you do not provide engine argument.

mockoon

Generate a mockoon workspace with response.

You should specify on each request :

• mockoon-label in extras to add label on endpoint.
• mockoon-label in responseExtras to add label on responses.
• mockoon-priority in responseExtras to sort responses, this is optional and default value is 0

Create your own engine

You can create your own engine by creating a typescript npm package, installing dumpy with npm i dumpy and by adding an export default class that herits DumpyEngine :

import DumpyEngine from "dumpy";
import DumpyEngineOutput from "dumpy/dist/models/output/DumpyEngineOutput";

export default class CustomEngine extends DumpyEngine {

    handleOutput(output: DumpyEngineOutput): void | Promise<void> {
        //do what you want
    }
    
}

Then compile your ts code into js file. You can now use your engine with --engine-custom argument :

dumpy --engine-custom <path to js file that contains CustomEngine class>