forge4flow / apirunner

A lightweight test runner for testing http APIs

API Runner

A lightweight test runner for testing http APIs. Define test cases as json and execute them against any server (local or over the network).

Written in Go. Built by the Warrant team.

Usage

Install

go get github.com/warrant-dev/apirunner

Define API tests as json

Sample test file:

{
    "ignoredFields": [
        "internalId"
    ],
    "tests": [
        {
            "name": "createUser",
            "request": {
                "method": "POST",
                "url": "/users",
                "body": {
                    "email": "[email protected]"
                }
            },
            "expectedResponse": {
                "statusCode": 200,
                "body": {
                    "userId": "{{ createUser.userId }}",
                    "email": "[email protected]"
                }
            }
        },
        {
            "name": "getUserById",
            "request": {
                "method": "GET",
                "url": "/users/{{ createUser.userId }}"
            },
            "expectedResponse": {
                "statusCode": 200,
                "body": {
                    "userId": "{{ createUser.userId }}",
                    "email": "[email protected]"
                }
            }
        },
        {
            "name": "deleteUser",
            "request": {
                "method": "DELETE",
                "url": "/users/{{ createUser.userId }}"
            },
            "expectedResponse": {
                "statusCode": 200
            }
        }
    ]
}

Execute tests

import (
	"github.com/warrant-dev/apirunner"
)

// Execute all tests in 'mytestfile.json' and print results
func main() {
    runner, err := apirunner.NewRunner(apirunner.Config{
        TestFileName:  "mytestfile.json",
        BaseUrl:       "http://localhost:8000",
        CustomHeaders: nil,
    })
    if err != nil {
        panic(err)
    }
    runner.Execute()
}

Features

• Supports all HTTP operations (GET, POST, PUT, DELETE etc.)
• Deep comparison of json responses (objects and arrays)
• Inject custom headers via config (useful for passing auth tokens)
• ignoredFields to ignore specific attributes during comparison (ex. non-deterministic ids, timestamps)
• Memoization of response attributes to support request chaining. For example, this test references an id of a resource created by a previous request:

{
    "name": "updateResourceTest",
    "request": {
        "method": "PUT",
        "url": "/resources/{{ createResourceTest.Id }}",
        "body": {
            "email": "[email protected]"
        }
    },
    "expectedResponse": {
        "statusCode": 200,
        "body": {
            "id": "{{ createResourceTest.Id }}",
            "email": "[email protected]"
        }
    }
}

Development

PRs welcome! Clone and develop locally:

git clone [email protected]:warrant-dev/apirunner.git
cd apirunner
go test

About Warrant

Warrant provides APIs and infrastructure for implementing authorization and access control.