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.
If disabled, all non-routed requests will be auto mocked with status code 200.

assert_all_called - (optional) bool - default: True
Asserts that all added and mocked routes were called when exiting context.

base_url - (optional) str
Base URL to match, on top of each route specific pattern and/or side effect.

Returns: Router

!!! note "NOTE" When using the default mock router respx.mock, without settings, assert_all_called is disabled.

!!! tip "pytest" Use the @pytest.mark.respx(...) marker with these parameters to configure the respx_mock pytest fixture.

.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, cookies=None, content=None, text=None, html=None, json=None, stream=None, content_type=None)

Parameters:

status_code - (optional) int - default: 200
Response status code to mock.

headers - (optional) dict | Sequence[tuple[str, str]]
Response headers to mock.

cookies - (optional) dict | Sequence[tuple[str, str]] | Sequence[SetCookie]
Response cookies to mock as Set-Cookie headers. See SetCookie.

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.

content_type - (optional) str
Response Content-Type header 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 "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.

!!! tip "Cookies" Use respx.SetCookie(...) to produce Set-Cookie headers.

SetCookie

A utility to render a ("Set-Cookie", <cookie header value>) tuple. See route respond shortcut for alternative use.

respx.SetCookie(name, value, path=None, domain=None, expires=None, max_age=None, http_only=False, same_site=None, secure=False, partitioned=False)

import respx
respx.post("https://example.org/").mock(
    return_value=httpx.Response(200, headers=[SetCookie("foo", "bar")])
)

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")))
respx.route(params="foo=bar&ham=spam")

!!! note "NOTE" A request querystring with multiple parameters of the same name is treated as an ordered list when matching. !!! tip "ANY value" Use mock.ANY as value to only match on parameter presence, e.g. respx.route(params={"foo": ANY}).

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, contains

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

Data

Matches request form data, excluding files, using eq as default lookup.

Key: data
Lookups: eq, contains

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

Files

Matches files within request form data, using contains as default lookup.

Key: files
Lookups: contains, eq

respx.post("https://example.org/", files={"some_file": b"..."})
respx.post("https://example.org/", files={"some_file": ANY})
respx.post("https://example.org/", files={"some_file": ("filename.txt", b"...")})
respx.post("https://example.org/", files={"some_file": ("filename.txt", ANY)})

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(headers=[("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"})

Files

api.md

Latest commit

History

api.md

File metadata and controls

API Reference

Router

Configuration

.route()

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

.request()

Route

.mock()

.return_value

.side_effect

.respond()

.pass_through()

Response

SetCookie

Patterns

M()

Method

Scheme

Host

Port

Path

Params

URL

Content

Data

Files

JSON

Headers

Cookies

Lookups

eq

contains

in

regex

startswith

Operators

AND (&)

OR (&)

INVERT (~)