responses: Mock Python Requests in Tests

Overview

Responses is a Python library for replacing outgoing calls made with requests with configured responses during tests. It helps developers test HTTP-dependent code predictably without relying on remote servers or creating live network side effects.

Tests can register responses by method and URL, then add matchers to validate request data and headers. The library also supports dynamic callbacks, request history and call-count inspection, and multiple ways to scope or manage mocks.

Key Features

• Register mock responses for HTTP methods, URLs, status codes, headers, and bodies.
• Activate mocks with a decorator, context manager, or explicit start and stop calls.
• Match request JSON, URL-encoded data, query parameters, headers, multipart data, fragments, and selected request arguments.
• Use callbacks to generate responses based on incoming requests.
• Choose default or ordered registries for matching and sequential response behavior.
• Inspect recorded calls and assert that requests were made the expected number of times.
• Configure passthrough rules for requests that should reach real servers.
• Record responses to YAML and load recorded responses into a registry. The README labels these features beta.

Use Cases

• Python application developers can test API client code without depending on the availability of external services.
• Test authors can check that requests contain expected parameters, headers, and bodies, not just that a response was received.
• Teams can model retry behavior or changing server responses by registering ordered responses for the same URL.
• Developers testing integrations can use callbacks to simulate responses that depend on request content.

Getting Started

Install with pip:

pip install responses

See the README for usage examples, matching options, and testing guidance.

Alternatives

• python-mocket: Mocket intercepts traffic at the socket level and supports multiple protocols and async clients, while responses targets Python Requests calls.
• HTTPretty: HTTPretty intercepts HTTP traffic at the socket level, while responses hooks into the Requests library.
• httmock: httmock also mocks calls made with Requests, using conditional URL matching and configured responses.

Considerations

• Requires Python 3.8 or newer and requests 2.30.0 or newer, according to the README.
• It targets the Python requests library. It is not presented as a general-purpose mock for other HTTP clients.
• Unmatched requests raise ConnectionError unless a passthrough rule allows them through.
• The README identifies response recording and replay as beta features, so their APIs may change.