API Mocking & Responses — Core Concepts

Why mock API responses

Every external API call in your tests is a liability. It introduces network latency, rate limit consumption, flakiness from server issues, costs from paid APIs, and environmental dependencies. A test that calls a real API isn’t testing your code — it’s testing the internet.

Mocking removes these variables. Your tests run in milliseconds, work offline, and produce the same result every time.

Three mocking approaches

1. Patching with unittest.mock

Python’s built-in unittest.mock library lets you replace any object at test time. For API clients, you typically patch the HTTP library’s method:

You replace requests.get or httpx.Client.get with a mock that returns a predefined response. This is the most common approach for simple cases.

Pros: no extra dependencies, works with any HTTP library. Cons: brittle if your code restructures how it calls the HTTP library. You’re testing the call pattern, not the HTTP behavior.

2. Transport-level mocking

Both httpx and requests support mock transports — fake HTTP layers that intercept requests before they reach the network. Your code creates a real client with a fake transport.

Pros: tests your full client code including headers, URL construction, and timeout handling. The mock operates at the HTTP level, not the Python function level. Cons: requires the HTTP library to support transport injection.

3. HTTP server mocking (responses, respx, VCR)

Libraries like responses (for requests), respx (for httpx), and vcrpy intercept HTTP calls at the library level. You register URL patterns and their responses before running your test.

Pros: clean API, tests realistic HTTP behavior, supports pattern matching on URLs. Cons: adds a test dependency. VCR specifically records real responses and replays them, which can be powerful but creates large fixture files.

What to mock and what not to

Mock: external API responses, third-party services, anything across a network boundary.

Don’t mock: your own code’s internal methods (this makes tests brittle), database queries (use a test database instead), file I/O for simple cases (use temporary directories).

The rule of thumb: mock at the boundary between your system and external systems.

Response fixtures: realistic test data

Good mocks return realistic data. Don’t return {"result": "ok"} when the real API returns a complex nested object with 20 fields. Copy a real response, anonymize it, and use it as your fixture.

Store fixtures as JSON files alongside your tests. This makes them reviewable in code review and reusable across multiple tests. When the API changes its response format, update the fixture and see which tests break.

Testing error scenarios

The real value of mocking isn’t testing the happy path — it’s testing failure modes:

• Timeout — does your code handle a slow response?
• 5xx errors — does it retry or fail gracefully?
• Rate limiting (429) — does it respect the Retry-After header?
• Malformed JSON — does it crash or handle it?
• Empty responses — does it handle missing fields?
• Partial data — what if a field the code expects is null?

Without mocking, testing these scenarios requires either breaking the real API (impossible) or waiting for it to break naturally (unreliable).

Common misconception

Developers often mock too much. If your test mocks the API client, the response parser, and the error handler, you’re testing nothing — you’ve replaced all the real behavior with fakes. Mock at one layer (the HTTP transport) and let everything above it run with real code. This gives you confidence that your parsing, error handling, and business logic actually work together.

The one thing to remember: Mock at the HTTP boundary, use realistic fixtures, and focus your mocking effort on error scenarios — that’s where bugs hide and where real APIs are hardest to test against.