responses

Warnings

• breaking In version 0.26.0, the behavior of `assert_all_requests_are_fired=True` (the default when using `responses.activate` as a context manager or decorator) changed. Assertions about unfired requests are now raised even if an exception occurs within the context manager or decorated function. Previously, these assertions were suppressed, which could hide uncalled mocks.
  Fix: Review tests that might rely on exceptions suppressing `responses` assertions. Adjust tests to explicitly handle the assertion failure, or set `assert_all_requests_are_fired=False` if this validation is not needed.
• deprecated Direct access to `assert_all_requests_are_fired`, `passthru_prefixes`, and `target` from the top-level `responses` module (e.g., `responses.assert_all_requests_are_fired`) is deprecated.
  Fix: Use the attributes via `responses.mock`, such as `responses.mock.assert_all_requests_are_fired`, `responses.mock.passthru_prefixes`, and `responses.mock.target` instead.
• deprecated The `match_querystring` argument in `Response` and `CallbackResponse` is deprecated.
  Fix: For matching query parameters, use `responses.matchers.query_param_matcher` for dictionary-based matching or `responses.matchers.query_string_matcher` for matching the raw query string.
• gotcha By default, `responses.add` assumes a mock should be consumed once. If `assert_all_requests_are_fired=True` (the default) is active, calling the same URL multiple times with a single `responses.add` definition will cause an `AssertionError` after the first call.
  Fix: For URLs expected to be called multiple times, set `repeat=True` in `responses.add()` (e.g., `responses.add(..., repeat=True)`), or add multiple `responses.add()` calls for each expected interaction.
• gotcha Prior to version 0.25.0, `matchers.header_matcher` did not correctly fail if a header specified in the matcher was entirely missing from the request; it only validated the value of present headers.
  Fix: Upgrade to `responses` 0.25.0 or later to ensure `matchers.header_matcher` properly validates the presence of matched headers.
• gotcha When using `responses` alongside other network mocking libraries (e.g., `httpretty`, `moto`) or attempting to make actual network calls within the same test context, conflicts can arise as `responses` extensively patches the `requests` library.
  Fix: Ensure `responses.activate`'s scope is properly managed and isolated to avoid interference. If possible, avoid combining multiple patching libraries for the same underlying network functionality in a single test, or use `responses.mock.passthru_all` or `responses.add_passthru` to allow specific real requests.

Install

• pip install responses Install latest version

Imports

• responses

  import responses

• activate

  from responses import activate

  Commonly used as a decorator: `@responses.activate`
• matchers

  from responses import matchers

  Used for advanced request body or header matching.

Quickstart

The quickstart demonstrates mocking a GET request using the `@responses.activate` decorator and `responses.add()` method. It sets up a mock response with a JSON body and then makes a `requests.get()` call, which is intercepted by `responses`. Finally, it asserts the response content and verifies that the mock was called.

import requests
import responses

@responses.activate
def test_example_request():
    responses.add(
        responses.GET,
        'http://example.com/api/test',
        json={'message': 'Hello, World!'},
        status=200,
        content_type='application/json'
    )

    # This request will be intercepted by 'responses'
    resp = requests.get('http://example.com/api/test')

    assert resp.status_code == 200
    assert resp.json() == {'message': 'Hello, World!'}

    # Verify that exactly one request was made to the registered URL
    assert len(responses.calls) == 1
    assert responses.calls[0].request.url == 'http://example.com/api/test'

print("Running test_example_request...")
test_example_request()
print("Test completed successfully.")