Testing code that calls external services
An order service takes payments through a gateway. The gateway is reached by a client class, an SDK or a thin HTTP wrapper, and every method on it does network I/O. The service code around it is yours and is exactly what you want to test: does it record the order correctly, does it cope when the gateway times out, does cancelling a paid order actually issue a refund. The gateway itself is what you cannot have in the test: no network, no sandbox account, no waiting for a real response.
Substituting the client for a stand-in works until the questions get
more specific: did the service charge the right amount exactly once,
did it refund the right charge, did the client’s own validation run?
wrapture leaves the client where it is and intervenes at the one method
that matters: stub the response, inject the timeout, or let the real
method run and adjust one thing about the call, and in every case
record what actually flowed so the test can assert on it. If you are
arriving from unittest.mock, the comparison page
maps each idiom you already know onto what is used here.
This example uses: call behaviour, recording on a timeline, filtering and asserting on events, binding groups, pytest fixtures and the pytest plugin.
The application code
The client shapes requests and parses responses like any SDK would; the
network edge is one private method, _post(), which here refuses to
run at all so that no test can depend on it by accident:
>>> import wrapture
>>> class PaymentClient:
... def __init__(self, api_key: str) -> None:
... self.api_key = api_key
...
... def charge(self, amount: int, currency: str = "USD") -> dict:
... if amount <= 0:
... raise ValueError(f"amount must be positive, got {amount}")
...
... response = self._post("/charges", {"amount": amount, "currency": currency})
...
... return {"id": response["id"], "amount": amount, "currency": currency}
...
... def refund(self, charge_id: str) -> dict:
... response = self._post(f"/charges/{charge_id}/refund", {})
...
... return {"id": response["id"], "charge": charge_id}
...
... def _post(self, path: str, payload: dict) -> dict:
... raise RuntimeError("no network in tests")
The service is the code under test. It records each order in memory, treats a gateway timeout as a recoverable outcome, and refunds on cancellation only if the order was actually paid:
>>> class OrderService:
... def __init__(self, client: PaymentClient) -> None:
... self.client = client
... self.orders: dict[str, dict] = {}
...
... def place(self, order_id: str, amount: int) -> dict:
... try:
... receipt = self.client.charge(amount)
... except TimeoutError:
... order = {"status": "pending", "amount": amount}
... else:
... order = {"status": "paid", "amount": amount, "charge_id": receipt["id"]}
...
... self.orders[order_id] = order
... return order
...
... def cancel(self, order_id: str) -> dict:
... order = self.orders[order_id]
...
... if order["status"] == "paid":
... self.client.refund(order["charge_id"])
...
... order["status"] = "cancelled"
... return order
>>> service = OrderService(PaymentClient(api_key="sk_test"))
>>> service.place("o-1", 500)
Traceback (most recent call last):
...
RuntimeError: no network in tests
The naive approach: swap the client out
The obvious move is to hand the service a fake client with the same method names that returns whatever the test wants. It works for the happy path, but the fake has to be kept in step with the real client by hand, it cannot express “the client’s own validation still runs”, and asking it what it was called with means building recording into the fake yourself. Each of those is something wrapture provides at the real client instead.
Stubbing the response, on the class
A binding names the method on the class, not on the instance the service
happens to hold, so it takes effect for every PaymentClient the
service constructs, however it constructs it. returns() answers the
call with a canned receipt and never reaches the real method, so
_post() is never touched:
>>> charge = wrapture.binding(PaymentClient, "charge")
>>> charge.on_call.returns({"id": "ch_TEST", "amount": 500, "currency": "USD"})
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with charge:
... service.place("o-1", 500)
{'status': 'paid', 'amount': 500, 'charge_id': 'ch_TEST'}
>>> service.orders["o-1"]
{'status': 'paid', 'amount': 500, 'charge_id': 'ch_TEST'}
The binding is a context manager, so the patch lasts exactly for the
block. Outside it charge() is the real method again, and the order
recorded inside the block is real state in the real service.
The stub answers without running charge(), but a call that would not
have fitted charge() is still refused, as the real method would
refuse it, so a service that drifts from the client’s signature cannot
pass its tests on the strength of the stub:
>>> with charge:
... service.client.charge(500, memo="gift")
Traceback (most recent call last):
...
TypeError: __main__:PaymentClient.charge (stubbed): got an unexpected keyword argument 'memo'
Injecting a timeout and checking the service copes
Swap the terminal behaviour to raises() and the service sees the
gateway time out. The point of the test is not that the exception is
raised, it is what the service does about it, and that code is real:
>>> charge.on_call.raises(TimeoutError("gateway timed out"))
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with charge:
... service.place("o-2", 300)
{'status': 'pending', 'amount': 300}
Behaviour persists on the binding across applications, so one charge
binding can be reconfigured from test to test rather than recreated.
A gateway that is down and then comes back is the more interesting
test, because it exercises both branches of place() in one run.
then(after=2) adds a second phase that takes over once the first has
handled two calls; the phase has the same verbs as on_call, and
nothing carries over from the first, so it starts empty:
>>> recovered = charge.on_call.then(after=2)
>>> recovered.returns({"id": "ch_RETRY", "amount": 300, "currency": "USD"})
<CallPhase 1 of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with charge:
... [service.place(f"o-{n}", 300)["status"] for n in (5, 6, 7)]
['pending', 'pending', 'paid']
>>> charge.phase
1
The first two orders were placed while the gateway timed out, the third
after it recovered, and charge.phase confirms the hand-over
happened. Phases restart on every application, so the same binding
would replay the outage for the next test. This one is done with it:
reset() drops every phase and leaves the binding bare.
>>> charge.on_call.reset()
<Binding '__main__:PaymentClient.charge' callable unapplied>
Running the real client code, with one thing changed
Sometimes the client’s own logic is part of what the test needs to
exercise: its validation, or the way it shapes a request. Move the stub
down to the network edge, and the real charge() runs above it:
>>> post = wrapture.binding(PaymentClient, "_post")
>>> post.on_call.returns({"id": "ch_LIVE_9f2"})
<CallBehaviour of <Binding '__main__:PaymentClient._post' callable unapplied configured>>
>>> with post:
... service.place("o-3", 250)
{'status': 'paid', 'amount': 250, 'charge_id': 'ch_LIVE_9f2'}
>>> with post:
... service.place("o-4", 0)
Traceback (most recent call last):
...
ValueError: amount must be positive, got 0
The receipt was assembled by the real charge(), and the zero amount
was rejected by the client’s real validation, which a canned response
would have skipped straight past.
With the real method running, transforms_args() and
transforms_result() change one side of the call while leaving the
rest of it alone. Here the currency is forced on the way in, and the
gateway’s id is pinned to a stable value on the way out, so assertions
do not depend on what a live gateway happened to return:
>>> charge.on_call.transforms_args(lambda args, kwargs: (args, {**kwargs, "currency": "EUR"}))
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> charge.on_call.transforms_result(lambda receipt: {**receipt, "id": "ch_TEST"})
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with post, charge:
... service.client.charge(250)
{'id': 'ch_TEST', 'amount': 250, 'currency': 'EUR'}
The reset() earlier left the binding bare, so the transforms compose
around the real call rather than around a leftover raises().
Recording what the service did to the gateway
Everything so far changed the call. To check that the service made
the right calls, open a timeline. The bindings given to timeline()
are applied for the block and every call through them lands on the tape
as an event, with real arguments, real results and real nesting:
>>> charge.on_call.passes_through()
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied>>
>>> refund = wrapture.binding(PaymentClient, "refund")
>>> with wrapture.timeline(charge, refund, post) as tape:
... _ = service.place("o-5", 700)
... _ = service.cancel("o-5")
... print(tape.tree())
__main__:PaymentClient.charge(amount=700, currency='USD') -> {'id': 'ch_LIVE_9f2', 'amount': 700, 'currency': 'USD'}
__main__:PaymentClient._post(path='/charges', payload={'amount': 700, 'currency': 'USD'}) -> {'id': 'ch_LIVE_9f2'} (injected)
__main__:PaymentClient.refund(charge_id='ch_LIVE_9f2') -> {'id': 'ch_LIVE_9f2', 'charge': 'ch_LIVE_9f2'}
__main__:PaymentClient._post(path='/charges/ch_LIVE_9f2/refund', payload={}) -> {'id': 'ch_LIVE_9f2'} (injected)
Only _post carries behaviour here; charge and refund are on the
timeline purely to be watched, and the tree marks the injected result
so a stubbed value is never mistaken for a real one.
Assertions go through each binding’s events, a filtered view of the
tape for that one call site, and work inside the block once the code
under test has run. with_args() matches on the normalized arguments,
so it does not matter whether the service passed the amount
positionally or by name. The same filtered logs serve as the steps of
tape.assert_order(), here saying the refund came after the charge
it refers to:
>>> with wrapture.timeline(charge, refund, post) as tape:
... _ = service.place("o-6", 700)
... _ = service.cancel("o-6")
... charged = charge.events.with_args(amount=700)
... refunded = refund.events.with_args(charge_id="ch_LIVE_9f2")
... _ = charged.assert_once()
... _ = refunded.assert_once()
... _ = post.events.assert_times(2)
... _ = tape.assert_order(charged, refunded)
The same recording answers the negative question. Cancelling an order
that never got paid must not refund anything, and assert_never() says
so, printing the events it looked at if it is wrong:
>>> charge.on_call.raises(TimeoutError("gateway timed out"))
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with wrapture.timeline(charge, refund):
... _ = service.place("o-7", 400)
... _ = service.cancel("o-7")
... _ = charge.events.raising(TimeoutError).assert_once()
... _ = refund.events.assert_never()
Declaring the expectation up front
An assertion has to be remembered at the end of the block. An expectation is declared on the binding before the block and verified automatically when the timeline exits, which suits the invariants a test always wants checked: one charge per order, one refund per cancelled paid order:
>>> charge.on_call.passes_through()
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied>>
>>> _ = charge.expect_once()
>>> _ = refund.expect_once()
>>> with wrapture.timeline(charge, refund, post):
... _ = service.place("o-8", 900)
... _ = service.cancel("o-8")
Nothing printed, because both expectations held. When one does not, the
timeline raises ExpectationNotMetError on exit, an AssertionError
subclass, listing the events it found. Suppose the gateway times out on
the charge and the order is later cancelled: the service correctly
refunds nothing, because nothing was paid, and the declared expectation
of one refund reports the mismatch without a line of assertion in the
block:
>>> charge.on_call.raises(TimeoutError("gateway timed out"))
<CallBehaviour of <Binding '__main__:PaymentClient.charge' callable unapplied configured>>
>>> with wrapture.timeline(charge, refund, post):
... _ = service.place("o-9", 900)
... _ = service.cancel("o-9")
Traceback (most recent call last):
...
wrapture.exceptions.ExpectationNotMetError: declared expectation on __main__:PaymentClient.refund not met: expected exactly 1 event(s), got 0
<EventLog __main__:PaymentClient.refund: 0 event(s)>
(no events)
Expectations persist on the binding like behaviour does, so a binding declared once at module scope carries its expectation into every test that uses it; the next section starts from fresh bindings for that reason.
Grouping the client’s methods
Two or three bindings on the same client soon want to move together.
bindings() declares them as one group with one lifecycle, each member
carrying its own behaviour, so a “gateway offline” scenario is one
object a test enters:
>>> offline = wrapture.bindings(charge=wrapture.binding(PaymentClient, "charge"),
... refund=wrapture.binding(PaymentClient, "refund"))
>>> _ = offline.charge.on_call.raises(TimeoutError("gateway timed out"))
>>> _ = offline.refund.on_call.raises(TimeoutError("gateway timed out"))
>>> with wrapture.timeline(offline):
... _ = service.place("o-10", 100)
... _ = offline.charge.events.raising(TimeoutError).assert_once()
... service.orders["o-10"]
{'status': 'pending', 'amount': 100}
A group passes straight to timeline(), and members are reached by
attribute for configuring behaviour and reading events. When the aim is
to watch every public method of the client rather than name each one,
wrapture.discover(PaymentClient, "*", exclude="_*") builds the same
kind of group by pattern; see
discovering members by pattern.
As a pytest suite
In a test file the same moves become fixtures. A yield fixture applies the binding for one test and removes it however the test ends, and because it yields the binding, a test that needs a different response reconfigures it in place:
import pytest
import wrapture
@pytest.fixture
def gateway():
charge = wrapture.binding(PaymentClient, "charge")
charge.on_call.returns({"id": "ch_TEST", "amount": 500, "currency": "USD"})
with charge:
yield charge
@pytest.fixture
def service():
return OrderService(PaymentClient(api_key="sk_test"))
def test_paid_order_records_the_charge(gateway, service):
assert service.place("o-1", 500)["charge_id"] == "ch_TEST"
def test_timeout_leaves_the_order_pending(gateway, service):
gateway.on_call.raises(TimeoutError("gateway timed out"))
assert service.place("o-2", 300)["status"] == "pending"
@wrapture.bound(PaymentClient, "_post").on_call.returns({"id": "ch_LIVE_9f2"})
@wrapture.bound(PaymentClient, "refund").expect_once()
def test_cancelling_a_paid_order_refunds_it(service, _post, refund):
service.place("o-3", 700)
service.cancel("o-3")
refund.events.with_args(charge_id="ch_LIVE_9f2").assert_once()
The first two tests share their binding through a fixture, which is the
right home for configuration several tests want. The third binds two
targets for itself alone, and uses the decorator form instead: each
wrapture.bound() line addresses a target exactly as binding()
would, applies a fresh binding around the test, and injects it under
the slot’s name, with the plugin’s tape fixture recording as usual.
The expect_once() declaration is the same up-front expectation shown
earlier, verified when the decorator removes the binding after a
passing test.
Scoping with decorators
covers the form.
Keep fixtures that apply bindings function scoped, the pytest default,
so no patch outlives the test that wanted it. wrapture’s pytest plugin
backs that up. Enable it once in conftest.py:
pytest_plugins = ["wrapture.pytest_plugin"]
Every test is then swept for a binding it applied and did not remove,
failing that test by name rather than letting the patch bleed into the
next one. The plugin also provides a tape fixture spanning the whole
test and attaches its call tree to the failure report, so a failing
order test shows what the service actually asked the gateway, not just
which assertion tripped.
Where next
Call behaviour
covers the full vocabulary, including validates_args() and
decorates() for what a transform cannot express, such as running the
real call and then raising to simulate a lost response.
Recording calls on a timeline
explains what each event holds, including the forwarded arguments the
real method received after a transform, and
filtering and asserting on events
lists every filter, assertion and declared expectation. For the
suite-level patterns, see
scoping with pytest fixtures
and the pytest plugin.