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

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

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

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.

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

A request querystring with multiple parameters of the same name is treated as an ordered list when matching.

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"})