responses: Mock HTTP Calls Made with Python Requests

Overview

responses is a Python utility for mocking HTTP calls made with the Requests library. It intercepts requests in tests and returns registered or callback-generated responses, so teams can exercise API client behavior without depending on a live server.

It is aimed at Python developers testing code that uses Requests, from simple GET and POST calls to request matching, redirects, retries, and concurrent calls. Tests can use a decorator or a context manager, and unmatched requests raise a connection error unless configured to pass through.

Key Features

• Register mock responses by HTTP method and URL, with status, body, JSON, and headers.
• Match requests by JSON or URL-encoded body, query parameters, headers, multipart data, fragments, and selected request arguments.
• Generate responses dynamically with callbacks, including callbacks that inspect request data.
• Choose default or ordered response registries to control how repeated requests are served.
• Inspect recorded calls and assert response call counts.
• Exercise error cases, redirects, and retry behavior without contacting the target service.
• Allow selected requests to pass through to real servers.
• Record real responses to YAML files and load them into a mock registry, a feature the project labels beta.

Use Cases

• A Python developer can test an API client’s handling of success and error responses without a network dependency.
• A team can verify that code sends the expected JSON payload, query parameters, or headers before accepting a mocked response.
• A maintainer can test retry limits and response sequences by registering ordered responses for repeated requests.
• A test author can simulate redirects, connection errors, or dynamic server behavior to cover less common paths.

Getting Started

Install with:

pip install responses

See the README for usage details, matchers, and configuration options.

Alternatives

• httmock: httmock matches requests by URL or handler and supplies responses, rather than using responses' request-registration interface.
• HTTPretty: HTTPretty intercepts traffic through fake sockets, while responses mocks at the Requests library level.
• python-mocket: Mocket intercepts socket and SSL traffic across multiple clients and protocols, rather than targeting Requests alone.
• vcrpy: VCR.py records and replays HTTP exchanges from cassette files, rather than defining mocked responses directly in tests.

Considerations

The library requires Python 3.8 or newer and Requests 2.30.0 or newer. The README identifies recording and replay from YAML files as beta functionality, so teams relying on those APIs should account for possible changes. The project is actively maintained, with recent commits and releases; its contributor base is not concentrated around one person. Issue closure is slower than pull request merging according to the supplied health data. The repository uses the Apache-2.0 license.