Skip to content

API Reference

Router

Configuration

Creates a mock Router instance, ready to be used as decorator/manager for activation.

respx.mock(assert_all_mocked=True, assert_all_called=True, base_url=None)

Parameters:

  • assert_all_mocked - (optional) bool - default: True
    Asserts that all sent and captured HTTPX requests are routed and mocked.
  • assert_all_called - (optional) bool - default: True
    Asserts that all added and mocked routes were called when exiting context.
    If disabled, all non-routed requests will be auto mocked with status code 200.
  • base_url - (optional) str
    Base URL to match, on top of each route specific pattern and/or side effect.

Returns: Router

NOTE

When using the default mock router respx.mock, without settings, assert_all_called is disabled.

.route()

Adds a new, optionally named, Route with given patterns and/or lookups combined, using the AND operator.

respx.route(*patterns, name=None, **lookups)

Parameters:

  • patterns - (optional) args
    One or more pattern objects.
  • lookups - (optional) kwargs
    One or more pattern keyword lookups, given as <pattern>__<lookup>=value.
  • name - (optional) str
    Name this route.

Returns: Route

.get(), .post(), ...

HTTP method helpers to add routes, mimicking the HTTPX Helper Functions.

respx.get(url, name=None, **lookups)

respx.options(...)

respx.head(...)

respx.post(...)

respx.put(...)

respx.patch(...)

respx.delete(...)

Parameters:

  • url - (optional) str | compiled regex | tuple (httpcore) | httpx.URL
    Request URL to match, full or partial, turned into a URL pattern.
  • name - (optional) str
    Name this route.
  • lookups - (optional) kwargs
    One or more pattern keyword lookups, given as <pattern>__<lookup>=value.

Returns: Route

respx.get("https://example.org/", params={"foo": "bar"}, ...)

.request()

respx.request(method, url, name=None, **lookups)

Parameters:

  • method - str
    Request HTTP method to match.
  • url - (optional) str | compiled regex | tuple (httpcore) | httpx.URL
    Request URL to match, full or partial, turned into a URL pattern.
  • name - (optional) str
    Name this route.
  • lookups - (optional) kwargs
    One or more pattern keyword lookups, given as <pattern>__<lookup>=value.

Returns: Route

respx.request("GET", "https://example.org/", params={"foo": "bar"}, ...)

Route

.mock()

Mock a route's response or side effect.

route.mock(return_value=None, side_effect=None)

Parameters:

  • return_value - (optional) Response
    HTTPX Response to mock and return.
  • side_effect - (optional) Callable | Exception | Iterable of httpx.Response/Exception
    Side effect to call, exception to raise or stacked responses to respond with in order.

Returns: Route

.return_value

Setter for the HTTPX Response to return.

route.return_value = Response(204)

.side_effect

Setter for the side effect to trigger.

route.side_effect = ...

See route.mock() for valid side effect types.

.respond()

Shortcut for creating and mocking a HTTPX Response.

route.respond(status_code=200, headers=None, content=None, text=None, html=None, json=None, stream=None)

Parameters:

  • status_code - (optional) int - default: 200
    Response status code to mock.
  • headers - (optional) dict
    Response headers to mock.
  • content - (optional) bytes | str | iterable bytes
    Response raw content to mock.
  • text - (optional) str
    Response text content to mock, with automatic content-type header added.
  • html - (optional) str
    Response HTML content to mock, with automatic content-type header added.
  • json - (optional) str | list | dict
    Response JSON content to mock, with automatic content-type header added.
  • stream - (optional) Iterable[bytes]
    Response stream to mock.

Returns: Route

.pass_through()

route.pass_through(value=True)

Parameters:

  • value - (optional) bool - default: True
    Mark route to pass through, sending matched requests to real server, e.g. don't mock.

Returns: Route

Response

NOTE

This is a partial reference for how to the instantiate the HTTPX Responseclass, e.g. not a RESPX class.

httpx.Response(status_code, headers=None, content=None, text=None, html=None, json=None, stream=None)

Parameters:

  • status_code - int
    HTTP status code.
  • headers - (optional) dict | httpx.Headers
    HTTP headers.
  • content - (optional) bytes | str | Iterable[bytes]
    Raw content.
  • text - (optional) str
    Text content, with automatic content-type header added.
  • html - (optional) str
    HTML content, with automatic content-type header added.
  • json - (optional) str | list | dict
    JSON content, with automatic content-type header added.
  • stream - (optional) Iterable[bytes]
    Content stream.

Patterns

M()

Creates a reusable pattern, combining multiple arguments using the AND operator.

M(*patterns, **lookups)

Parameters:

  • patterns - (optional) args
    One or more pattern objects.
  • lookups - (optional) kwargs
    One or more pattern keyword lookups, given as <pattern>__<lookup>=value.

Returns: Pattern

import respx
from respx.patterns import M
pattern = M(host="example.org")
respx.route(pattern)

See operators for advanced usage.

Method

Matches request HTTP method, using eq as default lookup.

Key: method
Lookups: eq, in

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

Scheme

Matches request URL scheme, using eq as default lookup.

Key: scheme
Lookups: eq, in

respx.route(scheme="https")
respx.route(scheme__in=["http", "https"])

Host

Matches request URL host, using eq as default lookup.

Key: host
Lookups: eq, regex, in

respx.route(host="example.org")
respx.route(host__regex=r"example\.(org|com)")
respx.route(host__in=["example.org", "example.com"])

Port

Matches request URL port, using eq as default lookup.

Key: port
Lookups: eq, in

respx.route(port=8000)
respx.route(port__in=[2375, 2376])

Path

Matches request URL path, using eq as default lookup.

Key: path
Lookups: eq, regex, startswith, in

respx.route(path="/api/foobar/")
respx.route(path__regex=r"^/api/(?P<slug>\w+)/")
respx.route(path__startswith="/api/")
respx.route(path__in=["/api/v1/foo/", "/api/v2/foo/"])

Params

Matches request URL query params, using contains as default lookup.

Key: params
Lookups: contains, eq

respx.route(params={"foo": "bar", "ham": "spam"})
respx.route(params=[("foo", "bar"), ("ham", "spam")])
respx.route(params="foo=bar&ham=spam")

URL

Matches request URL.

When no lookup is given, url works as a shorthand pattern, combining individual request URL parts, using the AND operator.

Key: url
Lookups: eq, regex, startswith

respx.get("//example.org/foo/")  # == M(host="example.org", path="/foo/")
respx.get(url__eq="https://example.org:8080/foobar/?ham=spam")
respx.get(url__regex=r"https://example.org/(?P<slug>\w+)/")
respx.get(url__startswith="https://example.org/api/")
respx.get("all://*.example.org/foo/")

Content

Matches request raw content, using eq as default lookup.

Key: content
Lookups: eq

respx.post("https://example.org/", content="foobar")
respx.post("https://example.org/", content=b"foobar")

Data

Matches request form data, using eq as default lookup.

Key: data
Lookups: eq

respx.post("https://example.org/", data={"foo": "bar"})

JSON

Matches request json content, using eq as default lookup.

Key: json
Lookups: eq

respx.post("https://example.org/", json={"foo": "bar"})

The json pattern also supports path traversing, i.e. json__<path>=<value>.

respx.post("https://example.org/", json__foobar__0__ham="spam")
httpx.post("https://example.org/", json={"foobar": [{"ham": "spam"}]})

Headers

Matches request headers, using contains as default lookup.

Key: headers
Lookups: contains, eq

respx.route(headers={"foo": "bar", "ham": "spam"})
respx.route(params=[("foo", "bar"), ("ham", "spam")])

Cookies

Matches request cookie header, using contains as default lookup.

Key: cookies
Lookups: contains, eq

respx.route(cookies={"foo": "bar", "ham": "spam"})
respx.route(cookies=[("foo", "bar"), ("ham", "spam")])

Lookups

eq

M(path="/foo/bar/")
M(path__eq="/foo/bar/")

contains

Case-sensitive containment test.

M(params__contains={"id": "123"})

in

Case-sensitive within test.

M(method__in=["PUT", "PATCH"])

regex

M(path__regex=r"^/api/(?P<slug>\w+)/")

startswith

Case-sensitive starts-with.

M(path__startswith="/api/")

Operators

Patterns can be combined using bitwise operators, creating new patterns.

AND (&)

Combines two Patterns using and operator.

M(scheme="http") & M(host="example.org")

OR (&)

Combines two Patterns using or operator.

M(method="PUT") | M(method="PATCH")

INVERT (~)

Inverts a Pattern match.

~M(params={"foo": "bar"})