Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 38 ยท Projects and Practice

Project: Testing an API Client

Test an API client without a network: inject a fake transport and a fake clock, check retries with backoff, error mapping, rate limits and caching, and learn how to design code for testability.

Almost every application talks to some web API: payments, weather, maps, your own microservices. Testing that code is a rite of passage. The real network is slow, flaky and sometimes costs money, so unit tests must never touch it, yet the code has interesting logic worth testing: retries, error handling, timeouts, caching, rate limits.

In this project you will write a small weather API client and test all of that without any network. The central idea is simple and reusable: make the client depend on a small transport object and a clock that you can replace in tests.

The design

The client never calls requests directly. It receives a transport: any object with a get(url, params) method that returns a response with status, json() and headers. In production you wrap requests or httpx in a ten-line adapter. In tests you pass a scripted fake that returns whatever you queue up, and records the calls.

flowchart LR
    T["test"] -->|"queues replies"| F["FakeTransport"]
    C["WeatherClient"] -->|"get(url, params)"| F
    C -->|"sleep(seconds)"| S["fake sleep (records)"]
    C -->|"now()"| K["fake clock"]
    F -->|"Response"| C

Everything slow or unpredictable (network, sleeping, time) is injected, so tests are instant and deterministic.

The behavior we want:

  • temperature(city) returns the temperature as a float.
  • A 404 raises CityNotFound; other 4xx errors raise ApiError immediately (retrying will not help).
  • A 5xx response or a timeout is retried up to 3 times with exponential backoff (1 s, 2 s, ...), then raises ApiUnavailable.
  • A 429 response waits for the number of seconds in its Retry-After header, then retries.
  • Results are cached for 60 seconds, per city.

Part 1: the client, retries and error mapping

Python A client with an injected transport and sleep

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at what the tests do not need: a network, real waiting, monkeypatching or mocking libraries. The sleeps list records the delays the client asked for, so the exponential backoff is verified instantly. FakeTransport has two honest limitations you should know: it only models what we scripted, and it cannot prove that the real service behaves the same way. That second gap is closed by a few integration tests (below).

Part 2: caching with a fake clock

Now add rule five, caching for 60 seconds, test first. The client needs the time, so we inject a clock function. The test controls it:

Python Caching with an injected clock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

test_entry_expires_after_ttl sits exactly on the boundary (> versus >=), the kind of edge a real clock would never let you hit on purpose. Without injecting the clock you would need time.sleep(60) or a library that patches the time globally.

Adapter, contract and integration tests

Fakes check your logic. They do not check that your assumptions about the real API are true. Close the gap with layers:

  1. Adapter test: the ten-line wrapper around requests is tested with an HTTP interception library (responses, respx) as in mocking the network: does it translate status codes, headers and timeouts correctly?
  2. Contract test: keep a few saved real responses (fixtures files) and assert your parsing handles them. When the provider changes a field, this test fails first.
  3. Integration test: a small number of tests that call the real or a sandbox API, marked @pytest.mark.integration, skipped by default and run nightly with a secret key (CI lesson).
Python
@pytest.mark.integration
def test_real_api_smoke(real_client):
    assert -90 < real_client.temperature("Oslo") < 60

What you practiced

  • Dependency injection replaced patching: transport, sleep and clock are arguments with production defaults.
  • A scripted fake (queue of replies, recorded calls) is a reusable test double kept in its own helper module (fakes.py).
  • Failure paths (404, 401, 429, 5xx, timeout) got as much attention as the happy path.
  • Observable side effects (sleeps, calls) verified backoff and caching without waiting.
  • Layered tests: many fast fake-based tests, a few adapter and integration tests.

Extensions

  • Add jitter to the backoff and test it by injecting a random function.
  • Add a circuit breaker: after five consecutive failures, stop calling for 30 seconds. Write the tests first.
  • Make the client async and rewrite the tests with an async fake (async lesson).
  • Add a timeout parameter and assert it is passed down to the transport.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the client receive its sleep function as an argument?

    Injecting sleep lets the test observe the requested delays (1, 2, 4 ...) without real waiting.
  2. 2. Why is a 404 not retried but a 503 is?

    Client errors mean the request itself is wrong, so retries would just repeat the failure. Server errors are often transient.
  3. 3. What does a scripted FakeTransport NOT prove?

    A fake only reflects your assumptions. Adapter, contract and integration tests check those assumptions against reality.
  4. 4. Why test the cache expiry exactly at the TTL boundary?

    An injected clock makes boundary testing trivial, and boundaries are the classic place for subtle bugs.

Summary

  • Inject the transport, the sleep function and the clock; give them production defaults.
  • A scripted fake transport with a reply queue and recorded calls makes API tests fast and deterministic.
  • Test every failure path: not found, client errors, rate limits, server errors, timeouts.
  • Verify backoff and caching through recorded sleeps and call counts, including boundary values.
  • Add a thin layer of adapter, contract and integration tests to keep the fakes honest.

Next: Practice: Reading and Fixing Failing Tests