Stubs are a type of test double that return a canned response based on the request. mountebank allows you to define a list of stubs when creating an imposter. mountebank associates both a list of responses and a list of predicates with each stub.
It doesn't make sense to create an empty array of responses, but each response is under no
obligation to override the defaults (every protocol defines a default for every response field;
see the protocol-specific documentation pages linked to from the sidebar for more details).
The responses array defines a circular buffer - every time the stub is used for the request,
the first response is pulled from the front of the responses array, evaluated, and pushed
to the back of the array. This elegantly does what you want. In the common case, when you
always want to return the same response, you just add one response to the array.
More complex scenarios will require that the same endpoint returns a sequence of
different responses for the same predicates. Simply add them all to the array in order.
When the sequence finishes, it will start over. More complexity can be added by simply
adding more responses to the array without complicating the contract.
Each stub response is defined by a specific response type that defines the behavior of the response. The response types currently supported are:
| Response Type | Description |
|---|---|
is |
Merges the specified response fields with the response defaults (see the protocol page linked to from the sidebar on the left for the defaults). |
proxy |
Proxies the request to the specified destination and returns the response. The response is saved and can be replayed on subsequent calls. |
inject |
Allows you to inject a JavaScript function to create the response object. |
See the proxy page and the injection page for detailed examples of those response types, and the predicates page for examples of stubs with predicates. Multiple stubs only make sense with predicates.
Responses can be parameterized. Right now, only one parameter is supported:
| Parameter | Default | Description |
|---|---|---|
repeat |
1 |
Repeats the response the given number of times. |
Stubs can be decorated by adding to the behaviors array. See the
behaviors page for more details.
Let's create an http imposter with a couple of is response types. It will simulate
a RESTful endpoint that creates a customer the first time it's called and returns a 400
the second time it's called because the email already exists. We add a second stub that returns a
404 on any request that isn't a POST to /customers/123
POST /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json
Content-Type: application/json
{
"port": 4545,
"protocol": "http",
"stubs": [
{
"predicates": [
{
"equals": {
"method": "POST",
"path": "/customers/123"
}
}
],
"responses": [
{
"is": {
"statusCode": 201,
"headers": {
"Location": "http://localhost:4545/customers/123",
"Content-Type": "application/xml"
},
"body": "<customer><email>customer@test.com</email></customer>"
}
},
{
"is": {
"statusCode": 400,
"headers": {
"Content-Type": "application/xml"
},
"body": "<error>email already exists</error>"
}
}
]
},
{
"responses": [
{
"is": { "statusCode": 404 }
}
]
}
]
}Let's assume the application under test makes the initial call...
POST /customers/123 HTTP/1.1
Host: localhost:4545
Accept: application/xml
Content-Type: application/xml
<customer>
<email>customer@test.com</email>
</customer>HTTP/1.1 201 Created
Location: http://localhost:4545/customers/123
Content-Type: application/xml
Connection: close
Date: Thu, 09 Jan 2014 02:30:31 GMT
Transfer-Encoding: chunked
<customer><email>customer@test.com</email></customer>...and the second call:
POST /customers/123 HTTP/1.1
Host: localhost:4545
Accept: application/xml
Content-Type: application/xml
<customer>
<email>customer@test.com</email>
</customer>HTTP/1.1 400 Bad Request
Content-Type: application/xml
Connection: close
Date: Thu, 09 Jan 2014 02:30:31 GMT
Transfer-Encoding: chunked
<error>email already exists</error>Now let's see the requests that mountebank
has saved for you:
GET /imposters/4545 HTTP/1.1
Host: localhost:<%= port %>
Accept: application/jsonHTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json; charset=utf-8
Content-Length: 4212
Date: Thu, 09 Jan 2014 02:30:31 GMT
Connection: keep-alive
{
"protocol": "http",
"port": 4545,
"numberOfRequests": 2,
"recordRequests": false,
"requests": [
{
"requestFrom": "::ffff:127.0.0.1:60523 ",
"method": "POST",
"path": "/customers/123",
"query": {},
"headers": {
"Accept": "application/xml",
"Host": "localhost:4545",
"Content-Type": "application/xml",
"Connection": "keep-alive",
"Transfer-Encoding": "chunked"
},
"body": "<customer>\n <email>customer@test.com</email>\n</customer>",
"ip": "::ffff:127.0.0.1 ",
"timestamp": "2014-01-09T02:30:31.022Z "
},
{
"requestFrom": "::ffff:127.0.0.1:60523 ",
"method": "POST",
"path": "/customers/123",
"query": {},
"headers": {
"Accept": "application/xml",
"Host": "localhost:4545",
"Content-Type": "application/xml",
"Connection": "keep-alive",
"Transfer-Encoding": "chunked"
},
"body": "<customer>\n <email>customer@test.com</email>\n</customer>",
"ip": "::ffff:127.0.0.1 ",
"timestamp": "2014-01-09T02:30:31.043Z "
}
],
"stubs": [
{
"predicates": [
{
"equals": {
"method": "POST",
"path": "/customers/123"
}
}
],
"responses": [
{
"is": {
"statusCode": 201,
"headers": {
"Location": "http://localhost:4545/customers/123",
"Content-Type": "application/xml"
},
"body": "<customer><email>customer@test.com</email></customer>"
}
},
{
"is": {
"statusCode": 400,
"headers": {
"Content-Type": "application/xml"
},
"body": "<error>email already exists</error>"
}
}
],
"_links": {
"self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/0" }
}
},
{
"responses": [
{
"is": { "statusCode": 404 }
}
],
"_links": {
"self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/1" }
}
}
],
"_links": {
"self": { "href": "http://localhost:<%= port %>/imposters/4545" },
"stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
}
}DELETE /imposters/4545 HTTP/1.1
Host: localhost:<%= port %>
The repeat behavior allows certain responses to return a certain number of times before
moving on to the next response in the array. In the below example, the first response is configured to
return 2 times before advancing to the second response:
POST /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json
Content-Type: application/json
{
"port": 7777,
"protocol": "http",
"stubs": [
{
"responses": [
{
"is": {
"body": "This will repeat 2 times"
},
"repeat": 2
},
{
"is": {
"body": "Then this will return"
}
}
]
}
]
}Now the first response will return 2 times before returning the second response.
GET / HTTP/1.1
Host: localhost:7777HTTP/1.1 200 OK
Connection: close
Date: Thu, 01 Jan 2015 02:30:31 GMT
Transfer-Encoding: chunked
This will repeat 2 timesGET / HTTP/1.1
Host: localhost:7777HTTP/1.1 200 OK
Connection: close
Date: Thu, 01 Jan 2015 02:30:31 GMT
Transfer-Encoding: chunked
This will repeat 2 timesGET / HTTP/1.1
Host: localhost:7777HTTP/1.1 200 OK
Connection: close
Date: Thu, 01 Jan 2015 02:30:31 GMT
Transfer-Encoding: chunked
Then this will returnDELETE /imposters/7777 HTTP/1.1
Host: localhost:<%= port %>