RESPX Documentation

Instead of patching the global HTTPX transport, you can use specific transport classes. This is useful when you want to pass a specific transport to an httpx.Client or httpx.AsyncClient instance directly.

• MockTransport: The base class for all mocking. respx.mock is an instance of this.
• SyncMockTransport: Use this for synchronous httpx.Client instances.
• AsyncMockTransport: Use this for asynchronous httpx.AsyncClient instances.

Mock transports accept the same configuration arguments as the respx.mock decorator/context manager.

import httpx
import respx

# Using SyncMockTransport with a Client
mock_transport = respx.SyncMockTransport()
request = mock_transport.get("https://foo.bar/", content="foobar")

with httpx.Client(transport=mock_transport) as client:
    response = client.get("https://foo.bar/")
    assert request.called
    assert response.status_code == 200
    assert response.text == "foobar"

# Using AsyncMockTransport with an AsyncClient
async def test_async():
    mock_transport = respx.AsyncMockTransport()
    request = mock_transport.get("https://foo.bar/", content="foobar")

    async with httpx.AsyncClient(transport=mock_transport) as client:
        response = await client.get("https://foo.bar/")
        assert request.called
        assert response.status_code == 200
        assert response.text == "foobar"

RESPX supports side_effect mocking, which behaves similarly to Python's built-in Mock object. side_effect takes precedence over return_value.

Function side effects

Functions are called with the captured request argument. They can:

• Return an httpx.Response.
• Raise an Exception.
• Return None to treat the route as a non-match (continuing to the next route).
• Return the input Request to pass the request through.
• Advanced: If the route uses regex with named groups, those groups are passed as kwargs to the function. You can also include a route argument to access call stats or modify the route.

Exception side effects

Pass an httpx.HTTPError subclass or any Exception to simulate request errors.

Iterable side effects

Pass an iterable (like a list) to return/raise different responses for repeated requests in order. Once the iterable is exhausted, a StopIteration is raised. You can use itertools to create infinite sequences.

import httpx
import respx

# 1. Function side effect with request and route
def my_side_effect(request, route):
    return httpx.Response(201, json={"id": route.call_count + 1})

@respx.mock
def test_side_effect():
    respx.post("https://example.org/").mock(side_effect=my_side_effect)
    
    response = httpx.post("https://example.org/")
    assert response.json() == {"id": 1}

# 2. Regex named groups passed as kwargs
def my_side_effect_kwargs(request, slug):
    return httpx.Response(200, json={"slug": slug})

@respx.mock
def test_regex_kwargs():
    route = respx.route(url__regex=r"https://example.org/(?P<slug>\w+)/")
    route.side_effect = my_side_effect_kwargs
    
    response = httpx.get("https://example.org/foobar/")
    assert response.json() == {"slug": "foobar"}

# 3. Exception side effect
@respx.mock
def test_connection_error():
    respx.get("https://example.org/").mock(side_effect=httpx.ConnectError)
    # ... triggers error

# 4. Iterable side effect
@respx.mock
def test_stacked_responses():
    route = respx.get("https://example.org/")
    route.side_effect = [httpx.Response(404), httpx.Response(200)]
    # First call returns 404, second returns 200

If you are migrating from requests-mock, follow these patterns:

Patching the Client

• Decorator: Use @respx.mock() and accept respx_mock: respx.Router as an argument.
• Context Manager: Use with respx.mock() as respx_mock:.

Mocking and Assertions

• Mocking: Use respx_mock.get().respond(json={}) instead of m.get(..., json={}).
• Exceptions: Set side_effect on the route (e.g., respx.post().side_effect = Exception()) instead of using the exc parameter.
• List of Responses: Pass a list to side_effect instead of passing a list to the mock method.
• Assertions:
  • Use respx.calls.assert_called_once() instead of m.called_once.
  • Access the last request via respx.calls.last.request and check properties like .url or .content (use json.loads(request.content) for JSON bodies).

# Example: requests-mock to respx migration
@respx.mock()
def test_some_call(self, respx_mock: respx.Router):
    respx_mock.get().respond(json={})

# Example: Assertions
respx.calls.assert_called_once()
assert str(respx.calls.last.request.url) == "https://api.io/example/endpoint"

Starting from RESPX version 0.15.0, response details are no longer passed as arguments directly to the request matching methods (like .post(), .get(), etc.). Instead, you must use .mock() or .respond() to define the response, or use the % operator for dictionary-based responses. This change separates request pattern matching from response configuration.

Migration Summary:

• Use .mock(return_value=Response(...)) for full control.
• Use .respond(...) for quick response definitions.
• Use the % operator for shorthand dictionary responses.
• Replace .add() with .route().

# Previously
respx.post("https://some.url/", status_code=200, content={"x": 1})

# Now (Option 1: Using .mock)
respx.post("https://some.url/").mock(return_value=Response(200, json={"x": 1}))

# Now (Option 2: Using .respond)
respx.post("https://some.url/").respond(200, json={"x": 1})

# Now (Option 3: Using % operator)
respx.post("https://some.url/") % dict(json={"x": 1})

# Migrating .add() to .route()
respx.route(method="POST", url="https://some.url/").respond(content="foobar")