User Guide

RESPX is a mock router, capturing requests sent by HTTPX, mocking their responses.

Inspired by the flexible query API of the Django ORM, requests are filtered and matched against routes and their request patterns and lookups.

Request patterns are bits of the request, like host method path etc, with given lookup values, combined using bitwise operators to form a Route, i.e. respx.route(path__regex=...)

A captured request, matching a Route, resolves to a mocked httpx.Response, or triggers a given side effect. To skip mocking a specific request, a route can be marked to pass through.

Mock HTTPX

To patch HTTPX, and activate the router, use the respx.mock decorator or context manager.

Using the Decorator

import httpx
import respx


@respx.mock
def test_decorator():
    my_route = respx.get("https://example.org/")
    response = httpx.get("https://example.org/")
    assert my_route.called
    assert response.status_code == 200

Using the Context Manager

import httpx
import respx


def test_ctx_manager():
    with respx.mock:
        my_route = respx.get("https://example.org/")
        response = httpx.get("https://example.org/")
        assert my_route.called
        assert response.status_code == 200

Router Settings

The RESPX router can be configured with built-in assertion checks and an optional base URL.

By configuring, a nested router is created, and the settings are locally bound to the routes added.

When decorating a test case with a configured router, the test function will receive the router instance as a respx_mock argument.

@respx.mock(assert_all_mocked=False)
def test_something(respx_mock):
    ...

See router configuration reference for more details.

Settings Examples:

@respx.mock(assert_all_called=False)
def test_something(respx_mock):
    respx_mock.get("https://example.org/")
    respx_mock.get("https://some.url/")  # Not called, yet not asserted

    response = httpx.get("https://example.org/")
    assert response.status_code == 200

with respx.mock(assert_all_mocked=False) as respx_mock:
    response = httpx.get("https://example.org/")  # Not mocked, yet not asserted
    assert response.status_code == 200

Base URL

When adding a lot of routes, sharing the same domain/prefix, you can configure the router with a base_url to be used for added routes.

import httpx
import respx

from httpx import Response


@respx.mock(base_url="https://example.org/api/")
async def test_something(respx_mock):
    async with httpx.AsyncClient(base_url="https://example.org/api/") as client:
        respx_mock.get("/baz/").mock(return_value=Response(200, text="Baz"))
        response = await client.get("/baz/")
        assert response.text == "Baz"

---

Routing Requests

The easiest way to add routes is to use the HTTP Method helpers.

For full control over the request pattern matching, use the route API.

HTTP Method Helpers

Each HTTP method has a helper function (get, options, head, post, put, patch, delete), shortcutting the route API.

my_route = respx.get("https://example.org/", params={"foo": "bar"})
response = httpx.get("https://example.org/", params={"foo": "bar"})
assert my_route.called
assert response.status_code == 200

See .get(), .post(), ... helpers reference for more details.

Route API

Patterns

With the route API, you define a combined pattern to match, capturing a sent request.

my_route = respx.route(method="GET", host="example.org", path="/foobar/")
response = httpx.get("https://example.org/foobar/")
assert my_route.called
assert response.status_code == 200

See .route() reference for more details.

Lookups

Each pattern has a default lookup. To specify what lookup to use, add a __<lookup> suffix.

respx.route(method__in=["PUT", "PATCH"])

Combining Patterns

For even more flexability, you can define combined patterns using the M() object, together with bitwise operators (&, |, ~), creating a reusable pattern.

hosts_pattern = M(host="example.org") | M(host="example.com")
my_route = respx.route(hosts_pattern, method="GET", path="/foo/")

response = httpx.get("http://example.org/foo/")
assert response.status_code == 200
assert my_route.called

response = httpx.get("https://example.com/foo/")
assert response.status_code == 200
assert my_route.call_count == 2

NOTE

M(url="//example.org/foobar/") is equal to M(host="example.org") & M(path="/foobar/")

Named Routes

Routes can be named when added, and later accessed through the respx.routes mapping.

This is useful when a route is added outside the test case, e.g. access or assert route calls.

import httpx
import respx

# Added somewhere else
respx.get("https://example.org/", name="home")


@respx.mock
def test_route_call():
    httpx.get("https://example.org/")
    assert respx.routes["home"].called
    assert respx.routes["home"].call_count == 1

    last_home_response = respx.routes["home"].calls.last.response
    assert last_home_response.status_code == 200

Nested Routers

As described under settings, a nested router is created when calling respx.mock(...).

Nested routers are useful when mocking multiple remote APIs, allowing grouped routes per API, and to be mocked individually and reused across tests.

Use the nested router as decorator or context manager to patch HTTPX and activate the routes.

import httpx
import respx

from httpx import Response


api_mock = respx.mock(assert_all_called=False)
api_mock.route(
    url="https://api.foo.bar/baz/",
    name="baz",
).mock(
    return_value=Response(200, json={"name": "baz"}),
)
...


@api_mock
def test_decorator():
    response = httpx.get("https://api.foo.bar/baz/")
    assert response.status_code == 200
    assert response.json() == {"name": "baz"}
    assert api_mock["baz"].called


def test_ctx_manager():
    with api_mock:
        ...

NOTE

Named routes in a nested router can be directly accessed via my_mock_router[<route name>]

---

Mocking Responses

To mock a route response, use <route>.mock(...) to either...

• set the httpx.Response to be returned.
• set a side effect to be triggered.

Mock a Response

Create a mocked HTTPX Response object and pass it as return_value.

respx.get("https://example.org/").mock(return_value=Response(204))

See .mock() reference for more details.

You can also use the <route>.return_value setter.

route = respx.get("https://example.org/")
route.return_value = Response(200, json={"foo": "bar"})

Mock with a Side Effect

RESPX side effects works just like the python Mock side effects.

It can either be a function to call, an exception to raise, or an iterable of responses/exceptions to respond with in order, for repeated requests.

respx.get("https://example.org/").mock(side_effect=...)

You can also use the <route>.side_effect setter.

route = respx.get("https://example.org/")
route.side_effect = ...

Functions

Function side effects will be called with the captured request argument, and should either...

• return a mocked Response.
• raise an Exception to simulate a request error.
• return None to treat the route as a non-match, continuing testing further routes.
• return the input Request to pass through.

import httpx
import respx


def my_side_effect(request):
    return httpx.Response(201)


@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.status_code == 201

If any of the route patterns are using a regex lookup, containing named groups, the regex groups will be passed as kwargs to the side effect.

import httpx
import respx


def my_side_effect(request, slug):
    return httpx.Response(200, json={"slug": slug})


@respx.mock
def test_side_effect_kwargs():
    route = respx.route(url__regex=r"https://example.org/(?P<slug>\w+)/")
    route.side_effect = my_side_effect

    response = httpx.get("https://example.org/foobar/")
    assert response.status_code == 200
    assert response.json() == {"slug": "foobar"}

A route can even decorate the function to be used as side effect.

import httpx
import rexpx


@respx.route(url__regex=r"https://example.org/(?P<user>\w+)/", name="user")
def user_api(request, user):
    return httpx.Response(200, json={"user": user})


@respx.mock
def test_user_api():
    response = httpx.get("https://example.org/lundberg/")
    assert response.status_code == 200
    assert response.json() == {"user": "lundberg"}
    assert respx.routes["user"].called

Exceptions

To simulate a request error, pass a httpx.HTTPError subclass, or any Exception as side effect.

import httpx
import respx


@respx.mock
def test_connection_error():
    respx.get("https://example.org/").mock(side_effect=httpx.ConnectError)

    with pytest.raises(httpx.ConnectError):
        httpx.get("https://example.org/")

Iterable

If the side effect is an iterable, each repeated request will get the next Response returned, or exception raised, from the iterable.

import httpx
import respx


@respx.mock
def test_stacked_responses():
    route = respx.get("https://example.org/")
    route.side_effect = [
        httpx.Response(404),
        httpx.Response(200),
    ]

    response1 = httpx.get("https://example.org/")
    response2 = httpx.get("https://example.org/")

    assert response1.status_code == 404
    assert response2.status_code == 200
    assert route.call_count == 2

Modulo Shortcut

For simple mocking, a quick way is to use the python modulo (%) operator to mock the response.

The right-hand modulo argument can either be ...

An int representing the status_code to mock:

respx.get("https://example.org/") % 204

response = httpx.get("https://example.org/")
assert response.status_code == 204

A dict used as kwargs to create a mocked HTTPX Response, with status code 200 by default:

respx.get("https://example.org/") % dict(json={"foo": "bar"})

response = httpx.get("https://example.org/")
assert response.status_code == 200
assert response.json() == {"foo": "bar"}

A HTTPX Response object:

respx.get("https://example.org/") % Response(418)

response = httpx.get("https://example.org/")
assert response.status_code == httpx.codes.IM_A_TEAPOT

Rollback

When exiting a decorated test case, or context manager, the routes and their mocked values, i.e. return_value and side_effect, will be rolled back and restored to their initial state.

This means that you can safely modify existing routes, or add new ones, within a test case, without affecting other tests.

import httpx
import respx

# Initial routes
mock_router = respx.mock(base_url="https://example.org")
mock_router.get(path__regex="/user/(?P<pk>\d+)/", name="user") % 404
...


@mock_router
def test_user_exists():
    # This change will be rolled back after this test case
    mock_router["user"].return_value = httpx.Response(200)

    response = httpx.get("https://example.org/user/123/")
    assert response.status_code == 200


@mock_router
def test_user_not_found():
    response = httpx.get("https://example.org/user/123/")
    assert response.status_code == 404

---

Pass Through

If you want a route to not capture and mock a request response, use .pass_through().

import httpx
import respx


@respx.mock
def test_remote_response():
    respx.route(host="localhost").pass_through()
    response = httpx.get("http://localhost:8000/")  # respose from server

See .pass_through() reference for more details.

---

Mock without patching HTTPX

The RESPX implements the HTTP Core transport interface.

If you don't need to patch HTTPX, pass a MockTransport as transport, when instantiating your HTTPX client, or alike.

import httpx
import respx
from respx.transports import MockTransport


router = respx.Router()
router.post("https://example.org/") % 404


def test_client():
    mock_transport = MockTransport(router=router)
    with httpx.Client(transport=mock_transport) as client:
        response = client.post("https://example.org/")
        assert response.status_code == 404

Hint

You can use RESPX not only to mock out HTTPX, but actually mock any library using HTTP Core transports.

---

Call History

The respx API includes a .calls object, containing captured (request, response) named tuples and MagicMock's bells and whistles, i.e. call_count, assert_called etc.

Asserting calls

assert respx.calls.called
assert respx.calls.call_count == 1

respx.calls.assert_called()
respx.calls.assert_not_called()
respx.calls.assert_called_once()

Retreiving mocked calls

A matched and mocked Call can be retrived from call history, by either unpacking...

request, response = respx.calls.last
request, response = respx.calls[-2]  # by call order

...or by accessing request or response directly...

last_request = respx.calls.last.request
assert respx.calls.last.response.status_code == 200

Local route calls

Each Route object has its own .calls, along with .called and .call_count shortcuts.

import httpx
import respx


@respx.mock
def test_route_call_stats():
    route = respx.post("https://example.org/baz/") % 201
    httpx.post("https://example.org/baz/")

    assert route.calls.last.request.url.path == "/baz/"
    assert route.calls.last.response.status_code == 201

    assert route.called
    assert route.call_count == 1

    route.calls.assert_called_once()

Reset History

The call history will automatically reset when exiting mocked context, i.e. leaving a decorated test case, or context manager scope.

To manually reset call stats during a test case, use respx.reset() or <your_router>.reset().

import httpx
import respx


@respx.mock
def test_reset():
    respx.post("https://foo.bar/baz/")
    httpx.post("https://foo.bar/baz/")

    assert respx.calls.call_count == 1
    respx.calls.assert_called_once()

    respx.reset()

    assert len(respx.calls) == 0
    assert respx.calls.call_count == 0
    respx.calls.assert_not_called()