Mocking API Requests in pytest with Python
Learn how to mock API requests in pytest using unittest.mock and monkeypatch. Simulate responses and errors, verify request arguments, and keep tests fast and deterministic.

Mocking API requests in pytest requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.
When you write pytest tests for code that calls external APIs, you need to mock API requests to keep tests fast and deterministic. This article shows how to mock API requests in pytest using unittest.mock and the monkeypatch fixture, and when a dedicated library like responses makes sense.
Why Mocking API Requests Matters in pytest
A test that makes a real HTTP request is slow, flaky, and dependent on network availability. It also risks hitting rate limits or modifying remote state. Mocking the request layer lets you test your code's logic—how it constructs URLs, handles status codes, parses JSON, and reacts to errors—without touching the network.
The core idea is to replace the function that performs the HTTP call with a stand-in that returns a controlled response. In Python, the most common target is requests.get, but the same technique applies to requests.post, requests.put, and other methods.
Patching requests.get with unittest.mock
The unittest.mock library provides the patch context manager, which can replace an attribute in a module or class for the duration of a test. When your code calls requests.get, you typically patch it at the module where it is used, not where requests is defined.
Consider this function that fetches a user profile:
# myapp/api.py
import requests
def get_user(user_id):
response = requests.get(
f"https://api.example.com/users/{user_id}",
timeout=5,
)
response.raise_for_status()
return response.json()To test it without a network call, patch requests.get and provide a fake response object:
# tests/test_api.py
from unittest.mock import patch, Mock
from myapp.api import get_user
def test_get_user_returns_parsed_json():
fake_response = Mock()
fake_response.raise_for_status.return_value = None
fake_response.json.return_value = {"id": 42, "name": "Alice"}
with patch("myapp.api.requests.get", return_value=fake_response) as mock_get:
result = get_user(42)
assert result == {"id": 42, "name": "Alice"}
mock_get.assert_called_once_with("https://api.example.com/users/42", timeout=5)The Mock object for the response has raise_for_status and json methods that return controlled values. The patch replaces requests.get inside myapp.api so the function never makes a real request.
Using pytest's monkeypatch Fixture
pytest provides the monkeypatch fixture, which is a more pytest-idiomatic way to replace attributes. It automatically undoes changes after each test, avoiding nested with blocks.
# tests/test_api.py
from unittest.mock import Mock
from myapp.api import get_user
def test_get_user_with_monkeypatch(monkeypatch):
fake_response = Mock()
fake_response.raise_for_status.return_value = None
fake_response.json.return_value = {"id": 7, "name": "Bob"}
monkeypatch.setattr("myapp.api.requests.get", Mock(return_value=fake_response))
result = get_user(7)
assert result == {"id": 7, "name": "Bob"}monkeypatch.setattr accepts a string path to the attribute. It also works with the actual module object if you prefer. The fixture restores the original requests.get after the test, even if the test raises an exception.
Simulating Different API Responses
Real APIs return different status codes, headers, and payloads. Your mock should be able to represent those variations. The key is to make the fake response object behave like a real requests.Response.
For example, to test a function that handles a 404 error:
# myapp/api.py
def get_user_or_none(user_id):
response = requests.get(f"https://api.example.com/users/{user_id}")
if response.status_code == 404:
return None
response.raise_for_status()
return response.json()# tests/test_api.py
def test_get_user_or_none_returns_none_on_404(monkeypatch):
fake_response = Mock()
fake_response.status_code = 404
monkeypatch.setattr("myapp.api.requests.get", Mock(return_value=fake_response))
assert get_user_or_none(999) is NoneYou can also simulate a successful response with custom headers by setting the headers attribute on the mock. For more complex scenarios, a MagicMock provides preconfigured magic methods, but explicit Mock configuration is usually clearer for ordinary response objects.
Verifying Request Arguments and Call Counts
Mocking is not just about returning data; it also lets you assert that your code made the correct request. The assert_called_once_with method checks both the call count and the exact arguments. For more granular checks, use mock_get.call_args or mock_get.call_args_list.
def test_get_user_verifies_request_url_and_timeout(monkeypatch):
fake_response = Mock()
fake_response.raise_for_status.return_value = None
fake_response.json.return_value = {}
mock_get = Mock(return_value=fake_response)
monkeypatch.setattr("myapp.api.requests.get", mock_get)
get_user(1)
args, kwargs = mock_get.call_args
assert args[0] == "https://api.example.com/users/1"
assert kwargs.get("timeout") == 5If your code calls requests.get multiple times, use mock_get.call_count or iterate over call_args_list to verify each call. This is especially useful when testing retry logic or pagination.
Handling Exceptions and Timeouts
External APIs can fail with network errors, timeouts, or invalid HTTP responses. Your mock should be able to raise these exceptions so you can test error-handling paths.
Use the side_effect parameter to make the mock raise an exception when called:
# myapp/api.py
def fetch_with_retry(url, retries=2):
for attempt in range(retries):
try:
response = requests.get(url, timeout=5)
response.raise_for_status()
return response.json()
except requests.Timeout:
continue
raise requests.Timeout(f"Failed after {retries} attempts")# tests/test_api.py
import pytest
from requests import Timeout
def test_fetch_with_retry_raises_after_timeouts(monkeypatch):
mock_get = Mock(side_effect=Timeout("timed out"))
monkeypatch.setattr("myapp.api.requests.get", mock_get)
with pytest.raises(Timeout):
fetch_with_retry("https://api.example.com/data")
assert mock_get.call_count == 2You can also use side_effect with a list to return different values on successive calls, which is useful for testing retry success scenarios.
Choosing Between unittest.mock and responses Library
While unittest.mock gives you full control, it can become verbose when you need to mock many endpoints or complex request matching. The responses library provides a higher-level interface that registers mock responses and automatically intercepts requests made through the requests library.
Here is the same test using responses:
# tests/test_api.py
import responses
from myapp.api import get_user
@responses.activate
def test_get_user_with_responses():
responses.add(
responses.GET,
"https://api.example.com/users/42",
json={"id": 42, "name": "Alice"},
status=200,
)
result = get_user(42)
assert result == {"id": 42, "name": "Alice"}responses matches the URL and method, and you can specify json, body, status, and headers. It also records the requests it intercepted, so you can assert on them. This approach reduces boilerplate when you have many endpoints.
The tradeoff is that responses only works with the requests library, not with httpx or aiohttp. If your code uses a different HTTP client, unittest.mock is the more portable choice. For a project that already uses requests exclusively, responses often leads to cleaner tests.
Keeping Mocks Maintainable in a Growing Test Suite
As your test suite grows, duplicated mock setup becomes a maintenance burden. A common pattern is to create a factory function that builds a fake response with the fields you need.
# tests/factories.py
import requests
from unittest.mock import Mock
def fake_response(status_code=200, json_data=None, headers=None):
resp = Mock()
resp.status_code = status_code
resp.headers = headers or {}
resp.json.return_value = json_data if json_data is not None else {}
if status_code >= 400:
resp.raise_for_status.side_effect = requests.HTTPError(f"{status_code} error")
else:
resp.raise_for_status.return_value = None
return respThen in tests you can write:
monkeypatch.setattr("myapp.api.requests.get", Mock(return_value=fake_response(json_data={"id": 1})))This keeps the mock behavior consistent and reduces the chance of forgetting to set raise_for_status or status_code. When the API contract changes, you update the factory in one place.
Another maintainability concern is patching the wrong module. Always patch where the name is looked up, not where it is defined. If your code does from requests import get, you must patch myapp.api.get instead of myapp.api.requests.get. A quick way to avoid this confusion is to always use import requests and call requests.get, which makes the patch target obvious.
Finally, decide whether your mock should be a Mock or a MagicMock. Both auto-create attributes when accessed, so neither catches typos by itself. If you want the mock to reject unexpected attributes, configure spec or spec_set, for example Mock(spec=requests.Response). In general, prefer Mock; choose MagicMock when you need preconfigured magic methods such as __len__ or __iter__.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.