killgrave

README

Killgrave

Killgrave is a simulator for HTTP-based APIs, in simple words a Mock Server, very easy to use made in Go.

Getting started

Install killgrave using go:

$ GO111MODULE=off go get -u github.com/friendsofgo/killgrave/cmd/killgrave

Install killgrave using homebrew:

$ brew install friendsofgo/tap/killgrave

Or you can download the binary for your arch on:

https://github.com/friendsofgo/killgrave/releases

Using Killgrave

Use killgrave with default flags:

$ killgrave
2019/04/14 23:53:26 The fake server is on tap now: http://localhost:3000

Or custome your server with this flags:

 -host string
        if you run your server on a different host (default "localhost")
 -imposters string
        directory where your imposter are saved (default "imposters")
 -port int
        por to run the server (default 3000)
 -version
        show the version of the application

How to use

Create an imposter

You must be create an imposter to start to use the application, only files with the .imp.json extension will be interpreted as imposters files, and the base path for the rest of the files will be the path of the .imp.json file.

You need to organize your imposters from more restrictive to less. We use a rule-based system for create each imposter, for this reason you need to organize your imposters in the way that more restrictive to less, like the example below.

imposters/create_gopher.imp.json

[
    {
        "request": {
            "method": "POST",
            "endpoint": "/gophers",
            "schemaFile": "schemas/create_gopher_request.json",
            "headers": {
                "Content-Type": "application/json",
                "Return-Error": "error"
            }
        },
        "response": {
            "status": 500,
            "headers": {
                "Content-Type": "application/json"
            },
            "body": "{\"error\": \"Server error ocurred\"}"
        }
    },
    {
        "request": {
            "method": "POST",
            "endpoint": "/gophers",
            "schemaFile": "schemas/create_gopher_request.json",
            "headers": {
                "Content-Type": "application/json"
            }
        },
        "response": {
            "status": 200,
            "headers": {
                "Content-Type": "application/json"
            },
            "bodyFile": "responses/create_gopher_response.json"
        }
    }
]

And its related files

schemas/create_gopher_request.json
{
    "type": "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": [
                        "gophers"
                    ]
                },
                "attributes": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string"
                        },
                        "color": {
                            "type": "string"
                        },
                        "age": {
                            "type": "integer"
                        }
                    },
                    "required": [
                        "name",
                        "color",
                        "age"
                    ]
                }
            },
            "required": [
                "type",
                "attributes"
            ]
        }
    },
    "required": [
        "data"
    ]
}

responses/create_gopher_response.json
{
    "data": {
        "type": "gophers",
        "id": "01D8EMQ185CA8PRGE20DKZTGSR",
        "attributes": {
            "name": "Zebediah",
            "color": "Purple",
            "age": 55
        }
    }
}

And then with the server on tap you can execute your request:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{
            "data": {
                "type": "gophers",
                "attributes": {
                "name": "Zebediah",
                "color": "Purple",
                "age": 55
                }
            }
    }' \
  http://localhost:3000/gophers

Docker

The application is also available through Docker, just run:

docker run -it --rm -p 3000:3000 friendsofgo/killgrave

Remember to use the -p flag to expose the container port where the application is listening (3000 by default).

NOTE: If you want to use killgrave through Docker at the same time you use your own dockerised HTTP-based API, be careful with networking issues.

Features

• Imposters created in json
• Validate json schemas on requests
• Validate requests headers
• Check response status
• All content-type bodies
• Write body files (XML, JSON, HTML...)
• Write bodies in line
• Regex for using on endpoint urls
• Allow write headers on response
• Allow imposter's matching by request schema
• Dynamic responses based on regex endpoint or request schema
• Dynamic responses based on headers
• Dynamic responses based on query params
• Allow organize your imposters with structured folders
• Allow write multiple imposters by file

Next Features

• Proxy server
• Record proxy server
• Better documentation with examples of each feature
• Validate request body XML

Contributing

Contributions are more than welcome, if you are interested please fork this repo and send your Pull Request.

License

MIT License, see LICENSE