requests-mock Documentation

At a low level, requests-mock provides a custom Adapter that can be mounted onto a requests.Session. This allows you to define specific URI patterns and their corresponding responses. When a request matches a registered URI, the adapter returns the mocked response.

import requests
import requests_mock

session = requests.Session()
adapter = requests_mock.Adapter()
session.mount('mock://', adapter)

# Register a URI with a specific method and response text
adapter.register_uri('GET', 'mock://test.com', text='data')

resp = session.get('mock://test.com')
print(resp.status_code, resp.text)
# (200, 'data')

The additional_matcher argument allows you to pass a callback function for dynamic matching logic. This function receives the request object as a parameter and must return True if the request matches, or False otherwise.

This is useful for inspecting request bodies (like JSON or XML) or other complex logic that standard matchers don't support.

def match_request_text(request):
    # request.text may be None; handle safely
    return 'hello' in (request.text or '')

adapter.register_uri('POST', 'mock://test.com/additional', additional_matcher=match_request_text, text='resp')

By default, requests_mock intercepts calls made via the global requests module. However, you can use the session parameter in requests_mock.Mocker to target a specific requests.Session instance. This ensures that the mocking only applies to that session and does not affect global requests or other sessions.

import requests
import requests_mock

url = "https://www.example.com/"
session = requests.Session()

# Only 'session' will be affected by this mocker
with requests_mock.Mocker(session=session) as session_mock:
    session_mock.get(url, text='session')
    print(session.get(url).text)  # Output: 'session'
    print(requests.get(url).text) # Output: (whatever global mock/real request is)

You can provide a dictionary to the request_headers argument. The mock will only match if the incoming request contains at least all the headers specified in your dictionary. Additional headers in the request are ignored.

# Matches if 'key': 'val' is present, regardless of other headers
adapter.register_uri('POST', 'mock://test.com/headers', request_headers={'key': 'val'}, text='resp')

To use requests-mock in your project, install it using pip:

pip install requests-mock

When using pytest, you do not need to import requests-mock or use the @requests_mock.Mocker decorator. Instead, requests-mock provides a built-in pytest fixture named requests_mock. You can use it by simply adding requests_mock as a parameter to your test function. This fixture provides the same interface as the requests_mock.Mocker class.

Note: If you are using pytest fixtures, avoid using the @requests_mock.Mocker decorator syntax found in some documentation examples, as it can conflict with how pytest handles function arguments.

import pytest
import requests

def test_url(requests_mock):
    requests_mock.get('http://test.com', text='data')
    assert 'data' == requests.get('http://test.com').text

To use the requests-mock fixture, you must have a dependency on the fixtures library. You can install this optional dependency by using the [fixture] extra with pip.

pip install requests-mock[fixture]

To emulate network-level issues like connection timeouts or SSL errors, use the exc parameter in register_uri instead of a body parameter. This will cause requests to raise the specified exception when the mock is hit.

import requests

# Emulate a connection timeout
adapter.register_uri('GET', 'mock://test.com/6', exc=requests.exceptions.ConnectTimeout)

# session.get('mock://test.com/6') will now raise requests.exceptions.ConnectTimeout