responses

Responses is a Python testing utility that intercepts calls made through the popular requests HTTP library and returns pre-registered mock responses instead of hitting real servers. It mirrors the requests API closely, so registering a fake endpoint feels familiar and requires almost no boilerplate.

Maintained by Sentry, responses lets you assert exactly which requests your code makes, match against bodies, query strings, and headers, and drive tests deterministically without a live network. It ships with type hints, a rich set of request matchers, and a recorder that can capture real traffic into reusable fixtures.

What You Get

• A @responses.activate decorator and RequestsMock context manager that intercept all requests traffic within their scope
• Shortcut helpers (responses.get, responses.post, etc.) and a Response object for registering mocked endpoints
• A comprehensive matchers module for asserting on JSON bodies, URL-encoded data, query params, headers, and request kwargs
• A recorder that captures real HTTP traffic into reusable YAML fixtures
• Built-in assertions that every registered response was fired and that unexpected calls raise ConnectionError

Common Use Cases

• Unit-testing code that calls external HTTP APIs without a live network connection
• Asserting that your client sends the correct method, URL, body, and headers
• Simulating error responses, timeouts, and exceptions to exercise failure paths
• Recording real API responses once and replaying them as deterministic fixtures

Under The Hood

Architecture - The core lives in responses/__init__.py, where a RequestsMock object holds a registry of registered responses and patches requests’ underlying HTTPAdapter.send (via unbound_on_send) so outgoing calls are matched against registered mocks rather than dispatched to the network. The activate decorator and context-manager protocol simply enter and exit this patched state, and registries.py provides pluggable ordering strategies (FIFO vs first-match) for how registered responses are selected.

Tech Stack - Pure Python (3.8+) with a small dependency surface: requests>=2.30, urllib3, and pyyaml for the recorder’s fixture format. Packaging is via setuptools/setup.py, typing is shipped through py.typed, and quality tooling includes mypy (mypy.ini), flake8, tox for multi-version matrices, and pytest with coverage.

Code Quality - The repo has an extensive responses/tests suite exercised across Python versions via tox, strict mypy typing, and a dedicated matchers.py module keeping request-matching logic isolated and unit-testable. A _recorder.py module cleanly separates the record-and-replay concern from the mocking core.

API Design - The public surface deliberately mirrors requests (responses.get, responses.post, Response(...)), which flattens the learning curve to near zero for anyone who already uses requests. Matchers compose as an iterable passed to match=, and clear deprecation tables in the README guide migration, making the ergonomics excellent.