strest-cli

:rocket: Flexible REST Tests

🔗 Connect multiple requests: Example Embed an authorization token you got as a response from a login request in your following requests automatically

📝 YAML Syntax: Write all of your tests in YAML files

🎉 Easy to understand: You'll understand the concept in seconds and be able to start instantly (seriously!)

Getting Started

# Via Yarn 
yarn global add strest-cli

# Via npm 
npm i -g strest-cli

# Via Docker 
# The image contains everything in the tests directory 
docker run -it eykrehbein/strest:latest tests/success/chaining/
 
# Bring your own test and environment 
docker run -it --env STREST_URL=https://jsonplaceholder.typicode.com -v ${PWD}:/app/data eykrehbein/strest:latest /data/tests/success/Env/

We'll be using the postman-echo test API in this tutorial.

To get started, we're using this file (The extension needs to be .strest.yml or .strest.yaml)

version: 1                            # only version at the moment 
 
requests:                             # all test requests will be listed here 
  testRequest:                        # name the request however you want 
    url: https://postman-echo.com/get  # required 
    method: GET                       # required 
    data:                             # valid data types: params + json or raw 
      params:
        foo1: bar1
        foo2: bar2
    # log: true # uncomment this to log the response 

To run the test, open your terminal and type

strest tests/success/postman.strest.yml

You may also run multiple test files at the same time by pointing to the directory, where the files are stored

strest # this will recursively search for all .strest.yml files in the cwd and it's subdirectories 
# or 
strest tests/success/chaining

Success! If you've done everything correctly, you'll get a response like this

[ Strest ] Found 4 test file(s)
[ Strest ] Schema validation: 4 of 4 file(s) passed

Executing tests in ./
✔ Testing login succeeded (0.463s)
✔ Testing verify_login succeeded (0.32s)
✔ Testing verify_login_chained succeeded (0.233s)
Executing tests in: ./var/
✔ Testing chaining_var1 succeeded (0.128s)
✔ Testing chaining_var2 succeeded (0.131s)

[ Strest ] ✨  Done in 1.337s

Writing .strest.yml test files

You can find a full Documentation of how to write tests here

Documentation

• How to write Tests
• Validation Types
• Examples
• Trello Board

Using & Connecting multiple requests

With traditional tools like Postman or Insomnia it's common to perform only a single request at a time. Moreover, you have to trigger each request on your own with a click on a button.

With Strest you're able to predefine a very well structured test file once, and every time you make any changes to your API you can test it with just one command in your terminal. Additionally, you can add hundreds or thousands of requests and endpoints which will run synchronously one after the other.

To create multiple requests, simply add multiple entries into the requests yaml object.

version: 1
 
requests:
  requestOne:
    ...
  requestTwo:
    ...
  requestThree:
    ...

Running this will result in something like

[ Strest ] Found 1 test file(s)
[ Strest ] Schema validation: 1 of 1 file(s) passed

✔ Testing requestOne succeeded (0.1s)
✔ Testing requestTwo succeeded (0.32s)
✔ Testing requestThree succeeded (0.11s)

[ Strest ] ✨  Done in 0.62s

Connecting multiple requests

What is meant by connecting multiple requests?

Connecting multiple requests means that you write a request and in each of the following requests you are able to use and insert any of the data that was responded by this request.

Usage

requests:
  
  login: # will return { token: "someToken" } 
    ...
 
  authNeeded:
    delay: 2000 # Wait 2 seconds for token to become valid 
    ...
    headers:
      Authorization: Bearer Value(login.token)
    ...
    validation:
      json:
        id: Value(login.users[0].id) # use arrays like you would in javascript 
 

As you could see, the usage is very simple. Just use Value(requestName.jsonKey) to use any of the JSON data that was retrieved from a previous request. If you want to use raw data, just use Value(requestName) without any keys.

You can use this syntax anywhere regardless of whether it is inside of some string like https://localhost/posts/Value(postKey.key)/... or as a standalone term like Authorization: Value(login.token)

This can also be used across files as demonstrated here

JsonPath

Using JsonPath is similar to using Value() but the queries can be more complex. This library is used.

Note: The syntax is not JsonPath() it is JsonPath{{}} This is because json path uses () in string matches

version: 1
requests:
  set_JsonPath:
    url: https://jsonplaceholder.typicode.com/posts
    method: POST
    data:
      json:
        phoneNumbers:
            - {type: iPhone, number: 0123-4567-8888}
            - {type: home, number: 0123-4567-8910}
  JsonPath:
    url: https://postman-echo.com/get
    method: GET
    data:
      params:
        foo: JsonPath{{set_JsonPath.phoneNumbers[?(@.type == "home")].number}}
    validate:
      json:
        args:
          foo: 0123-4567-8910

Practice here

Using random values with Faker

If you need to generate some random values, you are able to do so by using Faker API templates.

Usage

version: 1
 
requests:
  userRequest:
    url: https://postman-echo.com/get
    method: GET
    data:
      params:
        name: Fake(name.firstName) Fake(name.lastName)
    log: true

Visit Faker.js Documentation for more methods

Replacing values with predefined environment variables

Usage

export STREST_URL=https://jsonplaceholder.typicode.com
strest tests/success/Env/environ.strest.yml

version: 1
# ensure the ENV var is set: `export STREST_URL=https://jsonplaceholder.typicode.com` 
requests:
  environment:
    url: Env(STREST_URL)/todos/1
    method: GET

Replacing values with predefined custom variables

Usage

version: 1
# Define variables here
variables:
  example_url: https://jsonplaceholder.typicode.com/todos/1
  example_id: 1
 
requests:
  test:
    url: Var(example_url) # Use them in any field
    ...
    validate:
      json: 
        id: Variable(example_id) # Both, Var() and Variable() are allowed

Only Execute If

With Strest you can skip a response by setting a match criteria

version: 1
 
requests:
  if_Set:
    url: https://jsonplaceholder.typicode.com/posts
    method: POST
    data:
      json:
        foo: 1
  skipped:
    if:
      operand: Value(if_Set.foo)
      equals: 2
    url: https://jsonplaceholder.typicode.com/todos/2
    method: GET
  executed:
    if:
      operand: Value(if_Set.foo)
      equals: 1
    url: https://jsonplaceholder.typicode.com/todos/2
    method: GET

Response Validation

With Strest you can validate responses either by a specific value or by a Type. List of all valid Types

Raw Validation

requests:
  example:
    ...
    validate:
      raw: "the response has to match this string exactly"

JSON Validation

requests:
  example:
    ...
    validate:
      json:
        user:
          name: Type(String) # name has to be of type String 
          id: Type(Null | Number | String) # id has to be of type Number, String or Null 
          iconUrl: Type(String.Url)
        someOtherData: "match this string"

JSON Path Validation

version: 1
 
requests:
  jsonpath:
    url: https://jsonplaceholder.typicode.com/posts
    method: POST
    data:
      json:
        myArray:
        - foo: 1
          bar: 1
        - foo: 2
          bar: 2
    validate:
      jsonpath:
        myArray.1.foo: 2

Read jsonpath for more info and see this file for more complex example

Header Validation

requests:
  example:
    ...
    validate:
      headers:
        content-type: application/json; charset=utf-8
        access-control-allow-credentials: Type(Boolean | String)

Response-Code Validation

requests:
  example:
    ...
    validate:
      code: 200 # only allow code 200 (default) 
  ...
  advanced:
    ...
    validate:
      code: 2xx # allow all numbers in range of 200-299 

Retry until validation succeeds

requests:
  waiter:
    url: https://postman-echo.com/time/now
    method: GET
    delay: 900
    validate:
      code: 200
      max_retries: 30
      raw: "Tue, 09 Oct 2018 03:07:20 GMT"

export STREST_GMT_DATE=$(TZ=GMT-0 date --date='15 seconds' --rfc-2822 | sed "s/+0000/GMT/g")
strest tests/success/validate/maxRetries.strest.yml

Errors

Strest is a testing library so of course, you'll run into a few errors when testing an endpoint. Error handling is made very simple so can instantly see what caused an error and fix it. If a request fails, the process will be exited with exit code 1 and no other requests will be executed afterwards.

Example of a Validation Error

[ Strest ] Found 1 test file(s)
[ Strest ] Schema validation: 1 of 1 file(s) passed

✖ Testing test failed (0.2s)

[ Validation ] The required item test wasn't found in the response data

[ Strest ] ✨  Done in 0.245s

Allow Insecure certs

Boolean to allow:

• insecure certificates
• self-signed certificates
• expired certificates

# Example 
allowInsecure: true
someRequest:
  url: ...
  method: ...

Print out the equivalent curl commands

To print out the equivalent curl commands for each request, add the following flag to the command

strest ... --output curl

Exiting on a failed request

By default, Strest will exit the process with an exit code 1 if any request failed. But you can also manipulate this by adding the -n or --no-exit flag into the command. This will instruct the program to go on with the following request if the request failed.

Bulk tests

Specify a list of tests or directories to execute.

strest tests/success/bulk.yml -b

Contents of bulk.yml:

---
- tests/success/postman.strest.yml
- tests/success/two.strest.yml
- tests/success/chaining/

Configuration

You can create a file in your Computer's home directory called .strestConfig.yml which will be the custom config for Strest.

Setup

config:
  primaryColor: "#2ed573" # Hexadecimal Color Code (don't forget the quotation marks) 
  secondaryColor: "#ff4757" # Hexadecimal Color Code 
  errorColor: "#576574" # Hexadecimal Color Code 
 

License

Strest is MIT Licensed