The command line REST tester¶
restest is a powerful command line tool for testing REST APIs.
Tests are defined in one or more JSON files, and can be run against any REST API.
restest you can control return responses and test values against an expected result / behaviour and also manipulate headers, cookies and call parameters.
Since it is a command line tool, it can be used in a CI/CD pipeline to test your API.
Main features of
- Support session based request
- Powerful path parser to extract keys in nested JSON structures
- Output of a complete
curlcommand for each request
- Dump of all headers and fields
- Supports Token authentication
- Support values extracting, storing and reusing during the script
- Data manipulation using Python string formatting rules to create custom strings and values
- Support for multiple test files
- Ability to dump machine status and load it back
- Macros to simplify test definition
- Postman collection export
- Clean debug output
Just download the latest version from the release page and extract the archive in a folder of your choice.
restest requires Python 3.10.
How to run it¶
Typically you run
restest from a command line with some parameters and one or more JSON files with the tests to be performed.
In its simplest form, you can run
restest with just a single file as argument, like this:
restest offers many more options, like:
~/src/restest$ restest --help
file Files containing the tests
-h, --help show this help message and exit
--base-url BASE_URL Base URL. This string overrides the 'system' parameter in JSON file
--curl Dumps CURL also on console (defaults on log only
--dry If set, no request is done for real
--dont-stop-on-error Flag to stop RESTest on error. This flag overrides the 'system' parameter in
--env If set, global vars will contain also environment variables
--env-load ENV_LOAD If set, global vars will be loaded from the specified file
--env-save ENV_SAVE If set, global vars will be saved to specified file
--no-colors If set, colors in console output are disabled
--postman POSTMAN Export activity to a Postman JSON file
The Postman Collection name
The base url to use in Postman instead of the real host
Name of the authorization header name
Value to use for authorization header
--key KEY [KEY ...] One or more keys to be added to the globals dict use key:value format
--log LOG Custom log file overriding the one in 'system'
--quiet If set, no output on console
-v, --version show program's version number and exit
--delay DELAY Delay in milliseconds between requests
--prefix PREFIX The API prefix URL
JSON file structure¶
restest uses a JSON file to define the tests to be performed, the main and most important section of the JSON file is the
actions section, which contains the list of actions to be performed.
Actions can be of two types:
- a request action, which is a request to be performed against the API
- an insternal script action which is related to
Request actions are the most important part of the JSON file, and they contain the
url keys to define the request to be performed.
Internal script actions are used to control the behaviour of
restest and contain the
action key to define the action to be performed.
Every action must contain a
method key is present, then the action is actually a
action key is present, then the action is a script command.
The simplest example¶
This is the smaller JSON file for
restest you can write
(note: name it
In this example, the JSON file is created with just one single action that will do a GET request to the
As you can see, the URI is incomplete, as it misses the
https part. Don't worry: you can specify it in the command line.
Specifying using the command line allows you to run the same tests on different URLs (for example, development and production environments).
Here is the shortest command line to execute the script above:
ACTION description for HTTP requests¶
Every action can have a title field. The text included in this field will be shown on console. Useful to tell the user what's going on.
- GET the
- POST the
- PUT the
- PATCH the
- DELETE the
HTTP methods are not supported, but planned in the future.
The partial URL to call. As you have seen before, you can specify the base URL with the
--base-url command line argument.
This is a
false flag which determines if the current call is authenticated. Default is
Defines the request content-type and mode. Possible values are:
- json the request is a
- form the request is a
This is a
false flag which determines if
restest should ignore an error occurring on this request.
status_code key you can specify the
HTTP Status Code you expect the call to return.
For example, if you make an unauthorized call to a specific endpoint, it should return a
403 Unauthorized return code.
If you do not specify
status_code key and your request returns a
restest will return an error, but if you know for sure that
your request is going to fail with a
403 return code, then you can specify it with:
restest action will succeed.
Default value for
If the request has parameters, you can specify them with the
params keyword and passing an array.
Here there is an example:
if the request is a
POST request, parameters will be sent in post data, if it is a
GET request, parameters will be added to the
url with the classic
name=value& format, correctly escaped.
If the request needs custom headers, you can add them with the
Provided headers are not manipulated in any way (so, be carefull with uppercase and lowercase letters).
You can add the usual variable escape feature in the
value field of your headers.
NOTE 1: headers can only contain
NOTE 2: authentication headers are still handled with the
NOTE 3: if you have the same header key in both
headers, the value from
headers will be used for this call.
If the action is a
post request, you can specify
files keyword, passing an array of files to be posted.
Here there is an example:
This is a
false flag. If set to
true the cookies will not be sent or read during this single request.
You can have a test failing when the request exceedes a certain amount of time defined by
max_time is set in milliseconds, so if you want to fail after one second, set it to
fields section allows you to collect values from the response and to save them inside
restest to future use.
It is a list of field names that can be also "mapped" to a new name in memory while saving. You can specify both string (to save the key / value in memory as is without name modification) or a list with two fields
[ orig_name, new_name ].
NOTE: Field extraction supports dotted notation for nested objects.
Here there is a code snippet. Suppose the response is a JSON object like this one:
You could save
auth_token as is and remap
user_id in this way:
tests section allows you to run tests against the request response.
It contains an array of tests structured in this way:
title(optional) a title of the running test
fieldis the name of the field to run the test against. Field can be one of the following:
- an attribute name of the returned object (eg.
- if the field is a list of values (eg,
tags: [ 'hello', 'world' ]) you can instruct to check against a specific value using the
square notation. For example:
world. Square notations also work when the returned object is just an array. In this case, omit the field name (since there isn't any) and just go for
and so on.
- the field name can use dotted notation to access an inner field. There is no limit to the nested field notation. Examples:
- an attribute name of the returned object (eg.
valueis the expected value
modeis how to test the
fieldvalue against the provided
value. You can use one of those conditions (if omitted, default is
valuemust be exactly the same as the value contained in
valuemust not exists
fieldis present in the returned object
valuemust be present inside the
fieldobject (eg. array or string) must be of the size defined in
fieldvalue must be greater than
fieldvalue must be greater than or equal to
fieldvalue must be lesser than
fieldvalue must be lesser than or equal to
fieldvalue must exist
fieldvalue must be different to
fieldvalue is an array or string with a size greater than
fieldvalue is an array or string with a size greater than or equal to
fieldvalue is an array or string with a size lesser than
fieldvalue is an array or string with a size lesser than or equal to
fieldvalue is an object that must match the object specified in
Here there is an example of two tests, the first one is checking if the first element in array has
id equal to 1.
The second checks if the second user in the array has the username
During tests or variable extraction, sometimes it is important to be able to access a nested value in the returning JSON object.
restest offers a very powerful path parser, that will help you reaching the node you want inside your structure. Let's see some examples.
First of all, suppose that the JSON returning is similar to this one:
Here there are some path examples:
"user.email"- returns the value of the field
email@example.com this example)
"user.perms."- returns the first element of the perms array (
adminin this example)
"preferences.[name=avatar]"- returns the object that has
"preferences.[name=children].value[value!=2]"- returns the first child of object with
childrenthat hasn't a
You can see a fully working example in
I'll add more examples during time.