API-scenario

Scenario API testing from the command line.

API-scenario is a simple command line tool that allow you to execute easily a scenario to test your APIs.

It is perfect to make end to end tests, you could use in your CI workflow to validate your deployment or just to test locally your development.

• Why this project?
• Installation
  • Install using Homebrew (mac and linux)
  • Install using Scoop (windows)
  • Install using .deb file (linux)
  • Install using .rpm file (linux)
  • Use docker image
• Command line usage
  • Version
  • Execute your scenario
    • Save result into file
• Creating Your First Test
  • The basic structure of the file
  • Our first step
• Steps
  • Pause
  • Request
    • Headers
    • Assertions
      • Assertion composition
      • Available source type
      • Available comparison type
• Request Chaining
  • Using Variables to Pass Data Between Steps
  • Extracting Data from JSON Body Content
  • Global Variables
  • Add / Override headers
  • Built-in Variables and Functions
  • Using Variables in Requests

Why this project?

Our goal is to have a simple command line tool that can run scenario to test your apis directly from the command line. You can create a scenario and start using it during development, but also use it in your CI/CD to validate your deployment.

You can use variables in your scenario, so you are sure to run the same test suite on each environment and be sure of your release.

Installation

All the binaries are available in the release.

Install using Homebrew (mac and linux)

If you are using Homebrew package manager, you can install api-scenario with Homebrew.

brew tap thomaspoignant/homebrew-tap
brew install api-scenario

Install using Scoop (windows)

If you are on Windows and using scoop package manager, you can install api-scenario with Scoop.

scoop bucket add org https://github.com/thomaspoignant/scoop.git
scoop install api-scenario

Install using .deb file (linux)

If you prefer to use directly the .deb file to install in your debian like linux distribution.
Don't forget to set the correct version number.

wget https://github.com/thomaspoignant/api-scenario/releases/download/vX.X.X/api-scenario_X.X.X_Tux_64-bit.deb && dpkg -i api-scenario_*.deb

Install using .rpm file (linux)

If you prefer to use directly the .rpm file to install in your centos/fedora like linux distribution.
Don't forget to set the correct version number.

wget https://github.com/thomaspoignant/api-scenario/releases/download/vX.X.X/api-scenario_X.X.X_Tux_64-bit.rpm && rpm -i api-scenario_*.rpm

Use docker image

To use the last version of our docker image you can pull thomaspoignant/api-scenario:latest.

docker pull thomaspoignant/api-scenario:latest

You can also pull all the version directly but also directly a major version.
Available images are:

• docker pull thomaspoignant/api-scenario:latest (target the latest version)
• docker pull thomaspoignant/api-scenario:vX (target the major version)
• docker pull thomaspoignant/api-scenario:vX.X (target the minor version)
• docker pull thomaspoignant/api-scenario:vX.X.X (target a specific version)

See docker hub page for usage.

Command line usage

Version

api-scenario version
# 0.1.0

Execute your scenario

To execute your scenario please use the run options and specify your scenario file.

api-scenario run --scenario="./scenario.json"

There are several options you can use with this command:

Save result into file

To keep history of your scenario execution you can export the results into a file. You just have to add the option --output-file="<your file location>" and it will save the result into a JSON file (If you prefer YAML result add --output-format=YAML).

Example:

api-scenario run --scenario="./scenario.json" --output-file="<your file location>" --output-format=YAML

Creating Your First Test

Creating a test is simple, you just have to write json or yaml file to describe you api calls, and describe assertions.

The basic structure of the file

name: Simple API Test Example
description: A full description ...
version: '1.0'
steps:
   - ...

{
 "name": "Simple API Test Example",
 "description": "A full description of your test scenario",
 "version": "1.0",
 "steps": [
   ...
 ]
}

This global fields allow to describe your scenario:

• name: The name of your scenario
• description: A complete description of what your scenario is doing
• version: The version of your scenario
• steps: Array of steps, it will describe all the steps of your scenario (see steps for more details).

Our first step

For our first step we will create a basic call who verify that an API answer with http code 200 when calling it.

- step_type: request
  url: {{baseUrl}}/api/users
  method: GET
  headers:
    Content-Type:
      - application/json
  assertions:
    - comparison: equal_number
      value: '200'
      source: response_status

{
  "step_type": "request",
  "url": "{{baseUrl}}/api/users",
  "method": "GET",
  "headers": {
    "Content-Type": ["application/json"]
  },
  "assertions": [
    {
      "comparison": "equal_number",
      "value": "200",
      "source": "response_status"
    }
  ]
}

We manipulate different concepts here.

• step_type: The type of the step, here we are using request because we want to test a rest API (see steps to see the list of available step types).
• url: The URL of our request, {{baseUrl}} will be replaced before the call (see Using Variables in Requests for details)
• method: The HTTP verb of our request.
• headers: The list of headers we sent with the request.
• assertions: This is the list of checks we are doing when we have received the response.
  • comparison: The type of check we are doing, here we are testing that number are equals.
  • value: The expected value
  • source: On what part of the response we are looking, here we are checking the response status.

Now the first scenario is build, we can run it (see complete scenario: YAML / JSON).

api-scenario run --scenario="examples/first-test.json" --variable="baseUrl:https://reqres.in"

What we are doing is here is running our scenario file, and we ask to replace every occurrence of {{baseUrl}} by https://reqres.in.

Steps

There are different types of steps who allow performs different types of actions.
To specify the type of a step we are using the property step_type is the step object.

If there is no step_type property we ignore the step.

Pause

pause is simple, it is a step that wait X seconds.
This is useful when you have asynchronous API and allows waiting before calling the next API in the scenario.

Example: Wait for 5 seconds

- step_type: pause
  duration: 5

{
  "step_type": "pause",
  "duration": 5
}

Request

request is the step who can call a REST Api.

Headers

Headers are represented by an object containing all the headers to send.
Each header is has the name of the header for key and an array of strings as value.

You can use variables in the headers, they will be replaced before sending the request (see Using Variables to Pass Data Between Steps or Global Variables).

Example:

headers:
    Accept-Charset:
      - utf-8
    Accept: 
      - application/scim+json
    Authorization:
      - {{auth}}

{
  "headers": {
      "Accept-Charset": [
        "utf-8"
      ],
      "Accept": [
        "application/scim+json"
      ],
      "Authorization": [
        "{{auth}}"
      ]
    }
}

Assertions

Assertions are a big part of api-scenario, this is the acceptance tests of your request, it will allow you to simply write test to verify that you endpoint is doing what you want.

Assertion composition

Example:

- comparison: equals
  property: schemas
  value: User
  source: response_json

{
  "comparison": "equals",
  "property": "schemas",
  "value": "User",
  "source": "response_json"
}

Available source type

Available comparison type

Request Chaining

Using Variables to Pass Data Between Steps

Request steps can define variables that extract data from HTTP responses returned when running the test. To create a variable, add a variables block to your step and specify the location of the data you'd like to extract from the response, and the name of this variable.

  variables:
    - source: response_json
      property: point
      name: active

{
  "variables": [
    {
      "source": "response_json",
      "property": "point",
      "name": "active"
    }
  ]
}

A variable is:

Extracting Data from JSON Body Content

Data from a JSON response body can be extracted by specifying the path of the target data using standard JavaScript notation. View sample JSON.

Global Variables

Some variables could be set up at launch, for that you can add options to the run command to pass it. Common values (base URLs, API tokens, etc.) that are shared across requests within a test, or tests within a bucket, should be stored in an Initial Variable. Once defined, the variable is available to all requests within the test.

To add a variable just use the option --variable or -V and specify the key:value of this variable.

./api-scenario run -F your_file.json --variable="baseUrl:http://www.google.com/" -V "token:token1234"

Note that if you create a variable in a step with the same name of a global variable it will override it.

Add / Override headers

Overriding headers works the same as global variables.
You can add a header for all your requests by using the option --header or -H, it will add or override the header for all requests.

./api-scenario run -F your_file.json --header="Content-Type:application/json" -H "Authorization: Bearer Token123"

Built-in Variables and Functions

Using Variables in Requests

Once a variable has been defined, you can use it in any subsequent request.
Variables can be used in any request data field including the method, URL, header values, parameter values and request bodies.

To include the value of a variable in a request, enter the name of the variable surrounded by double braces e.g. {{variable_name}}.
If a variable is undefined when a request using that variable is executed, we will keep the variable un-replaced.