flat-test-service-client
Use when testing one external-service HTTP client class with its transport stubbed — URL assembly, the outgoing request, response parsing, timeouts, translation into the service's catalog exception —
SKILL.mdplugins/pyhouse-flat/skills/flat-test-service-client/SKILL.md
GitHubFlat-Layered Test — Service Client
Consult test-principles for the testing constitution. Where this skill contradicts test-principles, the constitution wins.
One unit-test file per client class, under the distribution's own tests/unit/. No database, no
container, no network — the httpx2.AsyncClient the test hands the client has a stub as its transport,
so everything the client itself does (URL assembly, headers, raise_for_status, JSON parsing, the
except httpx2.HTTPError translation) runs unchanged. That is why this is a unit test despite involving HTTP: nothing crosses a
process boundary.
The client has no Protocol and needs none. The test substitutes the transport, which is somebody else's
boundary — not an abstraction invented to make the code mockable.
When to use vs. neighbours
- The client wraps a vendor SDK rather than raw
httpx2(a cloud SDK, a database driver) → not a stub transport; test it against the real thing in a container under this distribution'stests/integration/, or, where there is no container for it, against the SDK's own test double if it ships one. - The filter/normalize function the client's output feeds → a plain unit test with no fixtures; it is pure and needs nothing from this skill.
- The work a trigger calls reaching this client →
flat-test-entrypoint, which stubs the same transport under the whole run against a real datastore, and so lives undertests/integration/. - The catalog exception this client translates to, and where it is declared →
exception-catalog; asserting the catalog's own shape is a separate unit test, not this skill. - Where the client module sits in a flat service's package layout →
flat-layered. - The family's shared datastore fixtures →
flat-test-integration-setup; nothing in this file needs one. - The shared groundwork — the substitution ladder, naming, AAA →
test-principles. - The client is an adapter behind a hexagonal
ICan<Verb>capability port rather than a flat*_client.py→hex-test-capability-adapter, in thepyhouse-hexplugin, whose HTTP-gateway flavor is the same stub transport bound to a port.
Template — pytest, httpx2.MockTransport under a real httpx2 client
tests/conftest.py — the upstream stub and the client over it, in the one conftest above both unit/
and integration/, because the tests of the work and of its wrapper use the same pair (test-principles,
fixture versus builder):
from collections.abc import AsyncIterator
import httpx2
import pytest
from myapp.qux import QuxClient
_QUX_URL = "https://qux.test"
_TIMEOUT_SECONDS = 1.0
@pytest.fixture
def qux_requests() -> list[httpx2.Request]:
return []
@pytest.fixture
def qux_answers() -> list[httpx2.Response | httpx2.TransportError]:
return []
@pytest.fixture
async def qux_client(
qux_requests: list[httpx2.Request], qux_answers: list[httpx2.Response | httpx2.TransportError]
) -> AsyncIterator[QuxClient]:
def answer(request: httpx2.Request) -> httpx2.Response:
qux_requests.append(request)
if not qux_answers:
pytest.fail(f"no answer queued for {request.method} {request.url}")
next_answer = qux_answers.pop(0)
if isinstance(next_answer, httpx2.TransportError):
raise next_answer
return next_answer
transport = httpx2.MockTransport(answer)
async with httpx2.AsyncClient(base_url=_QUX_URL, timeout=_TIMEOUT_SECONDS, transport=transport) as http:
yield QuxClient(http)
tests/unit/test_qux_client.py:
import httpx2
import pydantic
import pytest
from myapp.exceptions import QuxRequestFailedError
from myapp.qux import QuxClient
from myapp.schemas import FooPayload
async def test_fetch_foos_returns_the_parsed_payloads(
qux_requests: list[httpx2.Request],
qux_answers: list[httpx2.Response | httpx2.TransportError],
qux_client: QuxClient,
) -> None:
qux_answers.append(httpx2.Response(200, json={"items": [{"id": "f1", "name": "alpha"}]}))
result = await qux_client.fetch_foos()
assert [(request.method, request.url.path) for request in qux_requests] == [("GET", "/foos")]
assert result == (FooPayload(id="f1", name="alpha"),)
@pytest.mark.parametrize("status", [400, 404, 500, 503])
async def test_non_2xx_becomes_a_qux_request_failed_error(
qux_answers: list[httpx2.Response | httpx2.TransportError], qux_client: QuxClient, status: int
) -> None:
qux_answers.append(httpx2.Response(status))
with pytest.raises(QuxRequestFailedError) as exc_info:
await qux_client.fetch_foos()
assert isinstance(exc_info.value.__cause__, httpx2.HTTPStatusError)
async def test_a_timeout_becomes_a_qux_request_failed_error(
qux_answers: list[httpx2.Response | httpx2.TransportError], qux_client: QuxClient
) -> None:
qux_answers.append(httpx2.ConnectTimeout("timed out"))
with pytest.raises(QuxRequestFailedError) as exc_info:
await qux_client.fetch_foos()
assert isinstance(exc_info.value.__cause__, httpx2.TimeoutException)
@pytest.mark.parametrize(
"body",
[b"<html>not json</html>", b'{"items": [{"name": "alpha"}]}'],
ids=["not-json", "missing-field"],
)
async def test_a_200_with_a_malformed_body_becomes_a_qux_request_failed_error(
qux_answers: list[httpx2.Response | httpx2.TransportError], qux_client: QuxClient, body: bytes
) -> None:
qux_answers.append(httpx2.Response(200, content=body))
with pytest.raises(QuxRequestFailedError) as exc_info:
await qux_client.fetch_foos()
assert isinstance(exc_info.value.__cause__, pydantic.ValidationError)
The stub's record, its answers and the client over it are fixtures, not module-level builders, because
the client has an end — its transport is closed at teardown — and the record and answers are fresh per
test; they sit in tests/conftest.py rather than in each test module because three files at two levels
take them. The client fixture builds its httpx2.AsyncClient exactly as the process definition does —
base URL and timeout from constants in place of settings — with the stub as its transport, so no test
can hold the client with anything but the stub under it (rule 7). The stub's handler records each request
in qux_requests and answers it with the next of the qux_answers the test queued: a response, or a
transport error it raises, which the client hands on carrying the request. A request the test queued no
answer for fails the test, even under a caller that catches every exception, so nothing unexpected is
answered quietly. Where the process definition hands the transport an auth flow (flat-layered rule
13), the fixture builds it the same way, and its login requests go through the same stub, so the tests
pin the refresh with answers queued in the order the flow sends its requests — the login's token, the
401, the second login's token, the success — and read qux_requests back as that sequence of method
and path, the last carrying the renewed credential. A second rejection raises the catalogue error with
the record ending on the resource request, so the rejection is the resource's and not a failed login;
a credential request that itself fails raises it too.
fetch_foos sends nothing beyond its method and path, so the recorded method and path are its request
pin (rule 3); a method that sends a query, a header or a body reads it back from the request in
qux_requests.
The error tests assert the translated class and its chained cause. fetch_foos takes no input, so its
context is empty; a method that takes one also asserts the context key set the raise site and its
test agree on — never the message text, which is free to change (exception-catalog). The malformed-body
cases cover both halves of parsing: a body that is not JSON, and JSON that does not fit the payload.
A caller's test makes this client fail at its transport (flat-test-entrypoint rule 1).
Other bindings
- A project already on
respx. It keeps it —respxthroughpytest-httpx2overhttpx2, routes answered with.respond(...)and read back from each route's call record. What the tests assert — the translation, the outgoing request, malformed bodies, timeouts — is unchanged, and so is the ban on extracting aProtocol. - A local ASGI app served in-process as the transport, where the stub must hold state across requests. The client already takes its transport pre-built, so nothing in it changes.
- A client on
httpx, httpx2's predecessor. The same API under the old import,httpx.MockTransportincluded, so only the import changes. - A different HTTP library —
aiohttpwithaioresponses,requestswithresponses. The interception point and the exception classes the client translates from change together; the catalogue exception it translates to, the cause-chaining requirement and every rule below are unchanged. - Recorded interactions — vcrpy cassettes. Response bodies come from a recording rather than a literal, which keeps them honest about the vendor's real shape; rule 3 then pins the cassette's recorded request. The timeout and malformed-body cases still have to be hand-written, because a cassette holds only what actually happened.
Rules
- The transport is stubbed, never the client (
test-principles, the substitution ladder, rung 2), and noProtocolis extracted for it (flat-layeredrule 3). A test that patchesQuxClient.fetch_foosis testing nothing; the parsing and translation under test live inside it. - Assert the translation, not just the type —
test-principles, Assert strength recipe 6: the catalogue class, itscontextkeys where the call takes an input (exception-catalogrule 11), and the translated failure as its cause, never the message. - Pin what the client sent beyond its method and URL —
test-principles, Intercepting HTTP rule 5 (read back fromqux_requestshere). - A 200 the client cannot parse is part of its contract —
test-principles, Intercepting HTTP rule 6; the template's two malformed cases are its two halves. - The base URL is a constant beside the fixture that builds the client, and is passed in. Never let
the test depend on a settings value — hand the client an HTTP client built with an explicit
base_url, which is why the client is handed its transport rather than building one. - Assert the request a test exercises reached the stub, on the stub's record —
test-principles, Intercepting HTTP rules 2 and 3 (qux_requestshere). - No test reaches a real host (
test-principles, Intercepting HTTP rule 1), and a stubbed body is copied from a documented or recorded response (Intercepting HTTP rule 7), never read live.
Hard stops
- The client swallows a transport or parsing failure internally, returning a default instead of raising
→ stop, fix the client (
exception-catalogrule 15); a boundary that hides its failures cannot be tested, and its caller cannot tell a failure from an empty answer. - The client returns raw
httpx2.Responseobjects to its caller → stop, fix the client (flat-layered); the client owns parsing, and a test cannot pin behaviour that lives in the caller. - The client is an adapter behind a hexagonal
ICan<Verb>port → stop, usehex-test-capability-adapter, in thepyhouse-hexplugin.