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.md

GitHub

Flat-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's tests/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 under tests/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 the pyhouse-hex plugin, 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 — respx through pytest-httpx2 over httpx2, 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 a Protocol.
  • 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.MockTransport included, so only the import changes.
  • A different HTTP library — aiohttp with aioresponses, requests with responses. 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

  1. The transport is stubbed, never the client (test-principles, the substitution ladder, rung 2), and no Protocol is extracted for it (flat-layered rule 3). A test that patches QuxClient.fetch_foos is testing nothing; the parsing and translation under test live inside it.
  2. Assert the translation, not just the type — test-principles, Assert strength recipe 6: the catalogue class, its context keys where the call takes an input (exception-catalog rule 11), and the translated failure as its cause, never the message.
  3. Pin what the client sent beyond its method and URL — test-principles, Intercepting HTTP rule 5 (read back from qux_requests here).
  4. 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.
  5. 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.
  6. Assert the request a test exercises reached the stub, on the stub's record — test-principles, Intercepting HTTP rules 2 and 3 (qux_requests here).
  7. 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-catalog rule 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.Response objects 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, use hex-test-capability-adapter, in the pyhouse-hex plugin.