Quickly Mock a Server with Localroast
Tags: mocks, api, testing, localhost
Published: 2018-10-22 14:24:58

---
title: Quickly Mock a Server with Localroast
published: true
description: Command line programme to mock external servers
tags: mocks, api, testing, localhost
---

One challenge commonly faced when developing against an API is the need to have a mock of the API which can be used to test the API client being developed. To solve this problem without having to go through setting up an integration environment, I created a tool to quickly mock an external API.

Introducing [localroast](https://github.com/caalberts/localroast), a command line programme that quickly starts a web server, serving mock responses for endpoints you need. All it takes is a JSON file that contains a list of mocks.

Let’s see this in an example, based on the Swagger Petstore API available at [Swagger Editor](https://editor.swagger.io/). Let’s take a few APIs from this example to work on:
- `GET /pet/{petId}`
- `POST /pet`
- `DELETE /pet/{petId}`
- `GET /user/login`

First of all, install `localroast` via `brew install caalberts/tap/localroast`.

Now create a file to contain the mocks, let’s call it `pets.json`
```json
[
  {
    "method": "GET",
    "path": "/pet/:pet_id",
    "status": 200,
    "response": {
      "id": 1,
      "category": {
        "id": 1,
        "name": "dogs"
      },
      "name": "Hachiko",
      "tags": [
        {
          "id": 1,
          "name": "japanese"
        }
      ],
      "status": "available"
    }
  },

  {
    "method": "POST",
    "path": "/pet",
    "status": 201,
    "response": {
      "id": 2,
      "category": {
        "id": 1,
        "name": "dogs"
      },
      "name": "Bolt",
      "tags": [
        {
          "id": 2,
          "name": "fictional"
        }
      ],
      "status": "available"
    }
  },

  {
    "method": "DELETE",
    "path": "/pet/:id",
    "status": 204,
    "response": {
      "status": "deleted"
    }
  },

  {
    "method": "GET",
    "path": "/user/login",
    "status": 400,
    "response": {
      "status": "invalid username/password supplied"
    }
  }
]
```

Start the mock server with `localroast pets.json`.
```shell
$ localroast pets.json                                                                                                           
INFO[0000] brewing on port 8080
```

As soon as the server is running, we can hit any of the APIs and receive the JSON response specified earlier.
```shell
$ curl -XPOST localhost:8080/pet
{ "id": 1, "category": { "id": 1, "name": "dogs" }, "name": "Hachiko", "tags": [ { "id": 1, "name": "japanese" } ], "status": "available" }

$ curl -XPOST localhost:8080/pet -D "{ \"name\": \"Bolt\" }"
{ "id": 2, "category": { "id": 1, "name": "dogs" }, "name": "Bolt", "tags": [ { "id": 2, "name": "fictional" } ], "status": "available" }

$ curl localhost:8080/user/login
{ "status": "invalid username/password supplied" }
```

Often, we need to keep testing between various scenarios, such as successful calls, error scenarios, bad requests, and many more. Localroast allows us to do so very easily by autoloading any changes to the file, making the change immediately available.

Say we want to test a valid login response, all we need to do is to update the login API response with a successful scenario.

```json
{
  "method": "GET",
  "path": "/user/login",
  "status": 200,
  "response": {
    "status": "logged in"
  }
}
```

As soon as the file is saved, we can see the server updating automatically.
```shell
INFO[0533] file changed: pets.json
INFO[0533] parsed new schema
INFO[0533] updating router with new schema
```

And now we’d get the new response if we hit the login API again.
```shell
$ curl localhost:8080/user/login
{ "status": "logged in" }
```

I hope this tool can speed up your development workflow. Any feedback, feature requests and pull requests are welcome.