# Stop a customer's bad JSON at the client, then test it offline

> Swap only the transport, and the same client calls the real API and runs its tests offline, with no code changes.

Original: https://fdetimes.net/en/guides/typed-python-client-offline-tests/

In your first week on a customer site, the thing you touch most is usually their internal API: poorly documented, slow, and now and then returning JSON that does not match its description. If your code reads `resp.json()["total"]` all over the place, one missing field is enough to break the demo. And the stack trace then points to a line buried three layers deep.

This guide helps you avoid that with a small, typed Python client built on httpx and Pydantic, plus a test suite that needs no network. You will work with a hypothetical orders API that has an `/orders/{id}` endpoint. The orders API is invented, but every function and class used here appears in the official documentation of httpx, Pydantic and pytest.

You need Python 3, a virtualenv and a few minutes of setup:

```bash
pip install httpx pydantic pytest
```

## Step 1: write the data contract as a model

Before calling the network, write down what you *believe* the API will return. This model is the contract between your code and the customer's system.

```python
# orders_client/models.py
from pydantic import BaseModel

class Order(BaseModel):
    id: int
    status: str
    total: float
```

According to the Pydantic documentation, whenever data does not match the model the library raises `ValidationError`. Conversely, when validation succeeds, Pydantic guarantees that the object's fields match the declared types. The client in this guide relies on that guarantee, so downstream code no longer has to wonder whether `total` exists.

**Check:** in a REPL, call `Order.model_validate_json('{"id": 1, "status": "new"}')`. You should see a `ValidationError` with one error entry of type `missing`, the message `Field required`, and `total` as the first element of `loc`.

## Step 2: why have only one httpx.Client?

Many people call `httpx.get()` directly in every function. That works, but the httpx documentation is clear: for anything beyond experimentation, one-off scripts or prototypes, use a `Client` instance. So a client for the customer's API should hold exactly one `httpx.Client` and reuse it for every request.

```python
# orders_client/client.py
import httpx
from .models import Order

class CustomerApiError(Exception):
    def __init__(self, status_code: int, body: str):
        super().__init__(f"Customer API returned {status_code}: {body[:200]}")
        self.status_code = status_code
        self.body = body

class OrdersClient:
    def __init__(self, base_url: str, transport=None, timeout: float = 10.0):
        self._http = httpx.Client(
            base_url=base_url, timeout=timeout, transport=transport
        )

    def get_order(self, order_id: int) -> Order:
        resp = self._http.get(f"/orders/{order_id}")
        try:
            resp.raise_for_status()
        except httpx.HTTPStatusError as exc:
            raise CustomerApiError(exc.response.status_code, exc.response.text) from exc
        return Order.model_validate_json(resp.content)

    def close(self) -> None:
        self._http.close()
```

Three decisions in this code deserve attention. The first is `base_url`: httpx prepends this URL to every request, so each method only passes a path. To move from staging to production, you change a single string.

The second is the timeout. By default httpx raises `TimeoutException` when the network stays silent for more than 5 seconds. That may be too short for a long-running report, or too long for an endpoint that ought to answer immediately.

Here the timeout is written out so that anyone reading the code understands it is a deliberate choice, not a forgotten default. The 10 seconds is only for illustration; for the real value, ask the customer for the endpoint's SLA.

The last decision is `raise_for_status()`. It turns every response outside the 2xx range into an `HTTPStatusError`, which carries both the request and the response. The client converts it into `CustomerApiError`, so for HTTP errors the layers above catch a project error instead of having to know about httpx's error classes.

The limits of this cut-down version should be stated plainly: `ValidationError` and `httpx.TimeoutException` still go straight up to the caller. `ValidationError` is left alone on purpose, so the tests in Step 4 show the bad payload clearly. In a real project you can wrap these two as well into your own errors; only then do the upper layers truly need to catch nothing but project errors.

**Check:** `get_order` returns an `Order`, not a `dict`. Your editor can now autocomplete `.total`.

## Step 3: what is the transport parameter for?

Note the `transport=None` parameter in the constructor, because this is what lets the tests run offline. According to the httpx documentation, `MockTransport` takes a handler function that maps each request to a predefined response. No real request leaves the machine.

Wiring it in is simple too, because `httpx.Client` already accepts a `transport` parameter: pass in `httpx.MockTransport(handler)` and you are done. The code under test stays the same; only the transport layer underneath is swapped.

James Bennett, in his post "Don't mock Python's HTTPX", recommends exactly this: use HTTPX's built-in mock transport rather than mocking HTTPX itself or its internals, to reduce dependence on mock objects and avoid a lot of trouble.

```python
# tests/test_client.py
import httpx
import pytest
from pydantic import ValidationError
from orders_client.client import OrdersClient, CustomerApiError

def handler(request: httpx.Request) -> httpx.Response:
    if request.url.path == "/orders/42":
        return httpx.Response(200, json={"id": 42, "status": "shipped", "total": 19.5})
    if request.url.path == "/orders/7":
        return httpx.Response(200, json={"id": 7, "status": "shipped"})
    return httpx.Response(404, json={"error": "not found"})

@pytest.fixture
def client():
    c = OrdersClient("https://api.customer.example", transport=httpx.MockTransport(handler))
    yield c
    c.close()
```

In pytest, a test function gets a fixture simply by declaring it as a parameter. Every test therefore shares a client running on the mock without repeating the setup.

## Step 4: test all three outcomes, not just the happy path

A client calling into a customer's system has at least three outcomes: correct data, data of the wrong shape, and an HTTP error. Each needs its own test.

```python
def test_order_ok(client):
    order = client.get_order(42)
    assert order.total == 19.5

def test_payload_missing_field(client):
    with pytest.raises(ValidationError):
        client.get_order(7)

def test_404_becomes_custom_error(client):
    with pytest.raises(CustomerApiError) as exc:
        client.get_order(999)
    assert exc.value.status_code == 404
```

Look closely at order 7. The API returns status 200, which looks like success, but `total` is missing. Without a model, the error only surfaces when some revenue function somewhere hits a `KeyError`.

With a model, `get_order(7)` stops immediately with a `ValidationError`, and the error entry names the `total` field with the message `Field required`. You know at once which field broke, and on which endpoint.

**Check:** turn off Wi-Fi and run `pytest -q`. All three tests should still pass.

**Key point:** A customer's bad data should be stopped at the client's door, never allowed into business logic.

## When should you move to pytest-httpx?

A hand-written handler is easy to follow, but it has a blind spot: if you prepare a response for a path the code never calls, the test still passes. pytest-httpx closes this gap. According to its documentation, a test fails at teardown if any registered response was never requested.

By default, pytest-httpx also immediately raises `httpx.TimeoutException` for any request that matches no registered response, so a test cannot quietly call out to the real network. Redowan Delowar also mentions respx, a library that intercepts httpx requests during tests and returns prepared responses. Both add a dependency; for a small client in your first week, the built-in `MockTransport` is enough.

## Common mistakes

The most common mistake is creating a new `httpx.Client` in every method or every loop iteration. That goes against the httpx documentation's advice, and `base_url` and the timeout end up scattered, so switching environments or adjusting the timeout means editing many places.

The second is catching a bare `Exception` and returning `None`. The client then swallows both `ValidationError` and `HTTPStatusError`, and you will lose an afternoon working out why the dashboard is empty.

The third is making the model too strict on day one, before you have seen real data. Run the client against a few real payloads from staging, then tighten the model gradually.

## How this helps on a customer site

When a deployment starts, write this client as early as possible, because it decides where errors will surface later.

If the customer changes the schema without warning, the `ValidationError` test and the error log at the client let you point straight at the problem: "the `total` field has been missing since yesterday's release".

The offline test suite also lets you keep working when you do not yet have VPN access or credentials, or when the customer's staging is down.

If you are aiming for an FDE role, put a repo like this in your portfolio: a typed client for a public API, with tests covering all three outcomes. On a CV, writing "typed client with offline tests for bad payloads and 4xx codes" is more convincing than "experience integrating APIs".

The customer's system will keep changing. What you control is where errors surface, and the best place is right at the client.

**Try this week:**

- Pick an endpoint you currently consume as a raw dict, write a Pydantic model for it and add a MockTransport test with a payload missing a field.
- Find places in your current code that call httpx.get() or create a new Client inside a loop, and consolidate them into one shared client with an explicit timeout.
- Install pytest-httpx in a scratch repo and see how a test fails when a registered response is never requested.

## Sources

- [Transports - HTTPX](https://www.python-httpx.org/advanced/transports/)

- [Models - Pydantic Validation](https://pydantic.dev/docs/validation/latest/concepts/models/)

- [Error Handling - Pydantic Validation](https://pydantic.dev/docs/validation/latest/errors/errors/)

- [Timeouts - HTTPX](https://www.python-httpx.org/advanced/timeouts/)

- [QuickStart - HTTPX](https://www.python-httpx.org/quickstart/)

- [Clients - HTTPX](https://www.python-httpx.org/advanced/clients/)

- [pytest_httpx | pytest fixture to mock HTTPX](https://colin-b.github.io/pytest_httpx/)

- [How to use fixtures - pytest documentation](https://docs.pytest.org/en/stable/how-to/fixtures.html)

- [Don’t mock Python’s HTTPX](https://www.b-list.org/weblog/2023/dec/08/mock-python-httpx/)

- [Shades of testing HTTP requests in Python](https://rednafi.com/python/testing-http-requests/)
