Guide¶
mbtest provides a Pythonic wrapper around Mountebank, an over-the-wire test double tool.
This guide covers the main concepts and common usage patterns.
Advanced Topics:
Getting started¶
The mock_server fixture launches a Mountebank process for the test session and shuts it
down when the session ends. Add it to your conftest.py:
import pytest
from mbtest import server
@pytest.fixture(scope="session")
def mock_server(request):
return server.mock_server(request)
This requires Mountebank to be installed:
$ npm install mountebank@2.9 --omit=dev
A minimal test:
import httpx
from hamcrest import assert_that
from brunns.matchers.response import is_response
from mbtest.matchers import had_request
from mbtest.imposters import Imposter, Predicate, Response, Stub
def test_request_to_mock_server(mock_server):
imposter = Imposter(Stub(Predicate(path="/test"), Response(body="sausages")))
with mock_server(imposter):
response = httpx.get(f"{imposter.url}/test")
assert_that(response, is_response().with_status_code(200).and_body("sausages"))
assert_that(imposter, had_request().with_path("/test").and_method("GET"))
The with mock_server(imposter): block registers the imposter with Mountebank and tears it
down on exit. imposter.url is only available inside the block, once Mountebank has
assigned the port.
Imposters¶
An Imposter is a mock server listening on a port. The port is
allocated randomly by Mountebank if you don’t specify one:
imposter = Imposter(Stub(), port=4567, name="my-service")
Multiple imposters can be started together in one with block:
with mock_server([imposter1, imposter2]):
...
The default_response parameter sets what Mountebank returns when no stub matches:
from mbtest.imposters.responses import HttpResponse
imposter = Imposter(
Stub(Predicate(path="/known"), Response(body="yes")),
default_response=HttpResponse(body="unknown endpoint", status_code=404),
)
Supported protocols are HTTP, HTTPS, SMTP, and TCP:
Imposter(Stub(), protocol=Imposter.Protocol.HTTPS)
Stubs¶
A Stub pairs predicates (conditions) with responses. Mountebank
evaluates stubs in order and uses the first one whose predicates match. An imposter with
multiple stubs implements a fallback chain:
imposter = Imposter(
stubs=[
Stub(Predicate(path="/api/orders"), Response(body="orders")),
Stub(Predicate(path="/api/items"), Response(body="items")),
Stub(responses=Response(status_code=404)), # fallback
]
)
Both predicates and responses accept a single object or a list.
Predicates¶
A Predicate matches on any combination of request fields:
Predicate(
path="/api/orders",
method="POST",
query={"status": "pending"},
headers={"Content-Type": "application/json"},
body='{"qty": 1}',
)
The default operator is equals. Other operators let you do partial and pattern matching:
Predicate(path="/api/", operator=Predicate.Operator.STARTS_WITH)
Predicate(body="error", operator=Predicate.Operator.CONTAINS)
Predicate(path=r"^/v\d+/", operator=Predicate.Operator.MATCHES)
Available operators: EQUALS, DEEP_EQUALS, CONTAINS, STARTS_WITH,
ENDS_WITH, MATCHES, EXISTS.
Combining predicates¶
Use & (AND), | (OR), and ~ (NOT) to build composite predicates:
# Both conditions must match
predicate = Predicate(path="/test") & Predicate(method="POST")
# Either condition matches
either = Predicate(path="/a") | Predicate(path="/b")
# Inverts the match
not_admin = ~Predicate(path="/admin")
When you pass a list of predicates to a Stub, Mountebank
treats them as an implicit AND — all predicates in the list must match. Using &
produces the same effect with a single, composable predicate object.
XPath and JSONPath¶
Predicates support XPath and JSONPath selectors for structured request bodies:
Predicate(xpath="//order/qty", body="1")
Predicate(jsonpath="$.order.qty", body="1")
Injection¶
For advanced cases, InjectionPredicate accepts a
JavaScript function string (requires --allowInjection on the Mountebank server):
from mbtest.imposters.predicates import InjectionPredicate
InjectionPredicate(inject="(request) => request.path === '/test'")
Responses¶
A Response defines what the mock server returns:
Response(
body="sausages",
status_code=200,
headers={"Content-Type": "text/plain"},
)
The body can be a string or any JSON-serialisable data structure.
Response behaviors¶
Latency — wait adds a delay in milliseconds:
Response(body="slow response", wait=500)
Cycling — provide a list of responses and Mountebank cycles through them in order, one per request:
Stub(
Predicate(path="/api"),
[Response(body="first"), Response(body="second"), Response(body="third")],
)
Repeat — repeat a response a given number of times before moving to the next:
Stub(
Predicate(path="/api"),
[Response(body="busy", repeat=3), Response(body="ok")],
)
Fault simulation¶
FaultResponse simulates network-level errors rather
than returning an HTTP response:
from mbtest.imposters.responses import FaultResponse
Stub(responses=FaultResponse(FaultResponse.Fault.CONNECTION_RESET_BY_PEER))
Available faults: CONNECTION_RESET_BY_PEER, RANDOM_DATA_THEN_CLOSE.
Injection¶
InjectionResponse accepts a JavaScript function
string for fully dynamic responses (requires --allowInjection):
from mbtest.imposters.responses import InjectionResponse
InjectionResponse(inject="(request, state) => ({ statusCode: 200, body: request.path })")
Stubbing vs. mocking¶
Stubbing means pre-programming the mock server with fixed responses and not asserting on what requests it received. Use it when you only care that your code doesn’t blow up.
Mocking means additionally asserting on the requests the mock server received. Use
had_request() for this.
In mbtest the distinction is just whether you call assert_that(imposter, had_request(...))
— the same Imposter object supports both. Request recording is
controlled by the record_requests parameter on the imposter (True by default, as
long as the Mountebank server is started with --debug, which the mock_server fixture
does automatically).
Assertions and matchers¶
Checking HTTP requests¶
had_request() verifies that an imposter recorded a matching request.
Build the criteria using the fluent with_ / and_ interface:
from hamcrest import assert_that, has_entry
from mbtest.matchers import had_request
assert_that(imposter, had_request().with_path("/api/orders").and_method("POST"))
assert_that(imposter, had_request().with_query({"status": "pending"}))
assert_that(imposter, had_request().with_headers(has_entry("Authorization", "Bearer token")))
Any PyHamcrest matcher can be used in place of a literal value:
from hamcrest import contains_string
assert_that(imposter, had_request().with_body(contains_string("qty")))
To match the parsed JSON body, use with_json:
from hamcrest import has_entries
assert_that(imposter, had_request().with_json(has_entries(qty=1)))
To check the number of times a request was received:
assert_that(imposter, had_request().with_path("/api").and_times(3))
The matcher can also be applied to the server object to check across all imposters:
with mock_server([imposter1, imposter2]) as server:
...
assert_that(server, had_request().with_method("GET"))
SMTP¶
Use the smtp_imposter() factory to create an SMTP imposter (defaults
to port 5525), then assert on emails received using email_sent():
import smtplib
from hamcrest import assert_that
from mbtest.imposters import smtp_imposter
from mbtest.matchers import email_sent
def test_sends_email(mock_server):
imposter = smtp_imposter()
with mock_server(imposter):
smtp = smtplib.SMTP()
smtp.connect(host=imposter.host, port=imposter.port)
smtp.sendmail(from_addr, [to_addr], message_string)
smtp.quit()
assert_that(imposter, email_sent(subject="Order confirmation", body_text="Thank you"))