mountebank

mountebank - over the wire test doubles

Fork me on GitHub

the apothecary

API Overview

mountebank, being a man of the people, prefers the simple words of the vernacular over the silvery speech of the priesthood. As if to prove the point, he speaks in a RESTful application/json rather than application/vnd.mountebank+json. While he does provide hypermedia, it is more as a convenience to you, with no professorial dictate that you follow the script provided. To show how committed he is to that principle, all resources are described below, complete with URL templates.

mountebank uses a basic set of HTTP status codes. He knows that a 200 or 201 will make you happiest, but unfortunately he cannot guarantee that you will always receive one of those codes. In the cases where the input you provide is malformed in some fashion, he will offer a humble apology for not being clear about what he needs, and respond with a 400. In situations where you ask for a port that mountebank is unable to reserve, he will return you a 403. Every effort has gone into providing response bodies to help you diagnose the problems. Each error response returned will have a code and message at a minimum. If extra information is available, mountebank will happily pass it to you. If you get stuck, email the group on the support page, along with your logs, and mountebank will happily assist you.

mountebank has made every effort to spare you from 5xx HTTP codes. If you are unfortunate enough to receive one, first you should know that mountebank is most embarrassed. Please report the issue with the log details, and mountebank will help make it right for you.

Capabilities

mountebank supports the following capabilities:

Capability Resource Contract
Get entry hypermedia home resource
Create a single imposter imposter resource
Get a single imposter imposter resource
Delete a single imposter imposter resource
Overwrite all imposters with a new set of imposters imposters resource
Get a list of all imposters imposters resource
Delete all imposters imposters resource
Get mountebank configuration and process information config resource
Get the logs logs resource

Get entry hypermedia

GET /

Contract: home resource

Unpretentious and welcoming, mirroring mountebank's simple good nature. This endpoint exists for those who aspire to the upper echelons of REST, though they may be disappointed at the lack of URLs for relationships.


GET / HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 226
Date: Sun, 05 Jan 2014 16:16:08 GMT
Connection: keep-alive

{
  "_links": {
    "imposters": {
      "href": "http://localhost:42963/imposters"
    },
    "config": {
      "href": "http://localhost:42963/config"
    },
    "logs": {
      "href": "http://localhost:42963/logs"
    }
  }
}

Create a single imposter

POST /imposters

Contract: imposter resource

Though he's not proud to admit it, mountebank employs an army of imposters to fulfill your orders. Because your needs are varied and sundry, his imposters are all different, and all are identified by a port number and associated with a protocol. The value you get out of mountebank always starts by creating an imposter, which represents a test double listening on a socket.

Parameters:

If you don't need stubbing, then the port and protocol are all you need. The parameters each type of imposter accepts are explained on the page for the particular protocol you're interested in. See the protocols section on the sidebar on the left.

mountebank expects that you will be responsible for providing the port, since you'll need to configure the application under test with the same port. However, the port is not required, and if you do not include it in the request, mountebank will randomly assign one for you and return the port number in the response.


POST /imposters HTTP/1.1
Host: localhost:42963
Accept: application/json
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http"
}

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Location: http://localhost:42963/imposters/4545
Content-Type: application/json; charset=utf-8
Content-Length: 190
Date: Sun, 05 Jan 2014 16:28:40 GMT
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": {
      "href": "http://localhost:42963/imposters/4545"
    }
  }
}

You would also create any stubs in the POST call. Imposters are not mutable through the API once created. The expected use case is that they are setup for a single test run and destroyed at the completion of the test. The examples page links to demonstrations of this pattern in multiple languages and for multiple protocols.

mountebank expects you to configure your application under test to point to the imposter. In the case above, that would mean that your application has an http dependency configured to http://localhost:4545. To retrieve a list of all imposters, simply issue a GET:

Get a single imposter

GET /imposters/:port

Contract: imposter resource

Retrieving an imposter is generally useful for one the following reasons:

Query Parameters:

Name Type Description
replayable boolean Set to true to retrieve the minimum amount of information for creating the imposter in the future. This leaves out the requests array, the matches array, and any hypermedia.
removeProxies boolean Set to true to remove all proxy responses (and stubs) from the response. This is useful in record-playback scenarios where you want to seed the imposters with proxy information but leave it out on subsequent test runs. You can recreate the imposter in the future by using the response.

GET /imposters/4545 HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 190
Date: Sun, 05 Jan 2014 16:59:33 GMT
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": {
      "href": "http://localhost:42963/imposters/4545"
    }
  }
}

Had we set the replayable query parameter, the requests array and _links elements would not be there. If we had any stubs, the matches array would also not be present regardless of whether we ran mb with the --debug command line parameter or not. None of those fields are used during the creation of an imposter.


GET /imposters/4545?replayable=true HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 55
Date: Sun, 05 Jan 2014 16:59:33 GMT
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "stubs": []
}

Delete a single imposter

DELETE /imposters/:port

Contract: imposter resource

As mentioned above, typically you want to delete the imposter after each test run. This frees up the socket and removes the resource. As a convenience, the DELETE call also returns the imposter representation just like a GET imposter would. This allows you to optimize the number of REST calls made during a test run when looking at the requests array for mock verification.

Query Parameters:

Name Type Description
replayable boolean Set to true to retrieve the minimum amount of information for creating the imposter in the future. This leaves out the requests array, the matches array, and any hypermedia.
removeProxies boolean Set to true to remove all proxy responses (and stubs) from the response. This is useful in record-playback scenarios where you want to seed the imposters with proxy information but leave it out on subsequent test runs. You can recreate the imposter in the future by using the response.

DELETE /imposters/4545 HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 190
Date: Sun, 05 Jan 2014 16:59:33 GMT
Connection: keep-alive

{
  "protocol": "http",
  "port": 4545,
  "numberOfRequests": 0,
  "requests": [],
  "stubs": [],
  "_links": {
    "self": {
      "href": "http://localhost:42963/imposters/4545"
    }
  }
}

Overwrite all imposters with a new set of imposters

PUT /imposters

Contract: imposters resource

Sometimes you want to create a batch of imposters in a single call, overwriting any imposters already created. This call is destructive - it will first delete all existing imposters. The output of a GET /imposters?replayable=true can directly be replayed through this call. This call is also used during startup if you set the --configfile command line flag.

Parameters:

You must provide mountebank an imposters array. Each element in the array is the same as what's needed to create a single imposter, the parameters for which vary by protocol. View the protocol pages on the left for details.


PUT /imposters HTTP/1.1
Host: localhost:42963
Content-Type: application/json

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "mode": "binary"
    },
    {
      "protocol": "smtp",
      "port": 4548
    }
  ]
}

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 619
Date: Sun, 05 Jan 2014 16:59:33 GMT
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4546"
        }
      }
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4547"
        }
      }
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4548"
        }
      }
    }
  ]
}

Get a list of all imposters

GET /imposters

Contract: imposters resource

This is where you will come to retrieve a list of all active imposters. By default, mountebank returns some basic information and hypermedia. If you want more information, either get the single imposter or use the replayable flag.

Query Parameters:

Name Type Description
replayable boolean Set to true to retrieve the minimum amount of information for replaying the set of imposters in the future through a mass create call. This leaves out the requests array, the matches array, and any hypermedia.
removeProxies boolean Set to true to remove all proxy responses (and stubs) from the response. This is useful in record-playback scenarios where you want to seed the imposters with proxy information but leave it out on subsequent test runs. You can recreate the imposter in the future by using the response.

GET /imposters HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 619
Date: Sun, 05 Jan 2014 16:58:25 GMT
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4546"
        }
      }
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4547"
        }
      }
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "numberOfRequests": 0,
      "_links": {
        "self": {
          "href": "http://localhost:42963/imposters/4548"
        }
      }
    }
  ]
}

Delete all imposters

DELETE /imposters

Contract: imposters resource

The surest way to reset to a clean slate is to delete all imposters. Any imposter sockets mountebank has open will be closed, and the response body will contain exactly what you need to mass create the same imposters in the future.

Query Parameters:

Name Type Description
replayable boolean Defaults to true. Set to false to retrieve the matches and requests arrays with the response. You can still mass create using this JSON; it just has extraneous information.
removeProxies boolean Set to true to remove all proxy responses (and stubs) from the response. This is useful in record-playback scenarios where you want to seed the imposters with proxy information but leave it out on subsequent test runs. You can recreate the imposters in the future by using the response.

DELETE /imposters HTTP/1.1
Host: localhost:42963
Accept: application/json

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 277
Date: Sun, 05 Jan 2014 16:58:25 GMT
Connection: keep-alive

{
  "imposters": [
    {
      "protocol": "http",
      "port": 4546,
      "stubs": []
    },
    {
      "protocol": "tcp",
      "port": 4547,
      "mode": "binary",
      "stubs": []
    },
    {
      "protocol": "smtp",
      "port": 4548,
      "stubs": []
    }
  ]
}

Get mountebank configuration and process information

GET /config

Contract: config resource

If you want to know about the environment mountebank is running it, this resource will give you what you need. It describes the version, command line flags, and process information.


GET /config HTTP/1.1
Host: localhost:42963
Accept: application/json

{
  "version": "1.4.1",
  "options": {
    "port": 2525,
    "pidfile": "mb.pid",
    "logfile": "mb.log",
    "loglevel": "info",
    "configfile": "",
    "allowInjection": true,
    "mock": true,
    "debug": true
  },
  "process": {
    "nodeVersion": "v4.2.0",
    "architecture": "x64",
    "platform": "darwin",
    "rss": 55255040,
    "heapTotal": 37113600,
    "heapUsed": 23185680,
    "uptime": 3.718,
    "cwd": "/Users/bbyars/Dropbox/src/mountebank"
  }
}

Get the logs

GET /logs

Contract: logs resource

Query Parameters:

Name Type Description
startIndex integer Set to array index of the first log entry you want returned.
endIndex integer Set to the array index of the last log entry you want returned

  GET /logs HTTP/1.1
  Host: localhost:42963
  Accept: application/json

{
  "logs": [
    {
      "level": "info",
      "message": "[mb:2525] mountebank v1.4.1 (node v4.2.0) now taking orders - point your browser to http://localhost:2525 for help",
      "timestamp": "2015-10-20T03:33:23.018Z"
    },
    {
      "level": "info",
      "message": "[mb:2525] GET /logs",
      "timestamp": "2015-10-20T03:33:25.429Z"
    }
  ]
}

In the rare scenario where mountebank is hosted on a different server and you need access to the logs, they are accessible through this endpoint.