pytest-httpx

pytest-httpx provides a comprehensive suite of tools for mocking HTTP interactions with httpx, including:

• Response Customization: Add JSON bodies, custom bodies, multipart bodies (files, etc.), non-200 status codes, and custom headers.
• Advanced Protocols: Support for HTTP/2.0.
• Dynamic Behavior: Add dynamic responses and raise exceptions.
• Verification: Check sent requests to ensure your code is making the expected calls.
• Configuration: Control how many responses are registered, allow reusing responses, and skip mocking for specific hosts.

When multiple registered responses match a request, pytest-httpx selects the first one that has not yet been sent (based on registration order).

• Exhaustion: If all matching responses have already been sent, the request will not be considered a match (unless can_send_already_matched_responses is enabled).
• Specificity: You can provide matching criteria (URL, method, headers, etc.) to ensure specific responses are sent only for specific requests.

Once installed, the httpx_mock pytest fixture intercepts every httpx request and replies with user-provided responses. This allows you to mock HTTP interactions in your tests without making actual network calls.

# Example usage pattern
# (Note: Specific code implementation follows in subsequent sections)

def test_my_request(httpx_mock):
    # Use httpx_mock to register responses
    pass

Use the httpx_mock fixture to register responses for both synchronous httpx.Client and asynchronous httpx.AsyncClient requests. By default, add_response() creates a 200 (OK) response with an empty body.

Note: If all registered responses are not used during a test, the test will fail at teardown unless the assert_all_responses_were_requested option is disabled.

import pytest
import httpx


def test_something(httpx_mock):
    httpx_mock.add_response()

    with httpx.Client() as client:
        response = client.get("https://test_url")


@pytest.mark.asyncio
async def test_something_async(httpx_mock):
    httpx_mock.add_response()

    async with httpx.AsyncClient() as client:
        response = await client.get("https://test_url")

By default, pytest-httpx mocks every request. To allow certain requests to pass through to the real network (e.g., for integration testing with a local service), use the should_mock option in the httpx_mock marker. Provide a callable that accepts an httpx.Request and returns True to mock it or False to let it pass through.

import pytest
import httpx

@pytest.mark.httpx_mock(should_mock=lambda request: request.url.host != "www.my_local_test_host")
def test_partial_mock(httpx_mock):
    httpx_mock.add_response()

    with httpx.Client() as client:
        # This request will NOT be mocked
        response1 = client.get("https://www.my_local_test_host/sub?param=value")
        # This request will be mocked
        response2 = client.get("https://test_url")

The httpx_mock fixture behavior can be customized using the @pytest.mark.httpx_mock marker. You can apply these configurations at different levels:

• Per test: Use @pytest.mark.httpx_mock(...) on the test function.
• Per module: Define pytestmark = pytest.mark.httpx_mock(...) at the module level.
• Whole test suite: Use pytest_collection_modifyitems in your root conftest.py to apply the marker to all items.

import pytest

# Per test
@pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
def test_something(httpx_mock):
    ...

# Per module
pytestmark = pytest.mark.httpx_mock(assert_all_responses_were_requested=False)

To test how your code handles network or protocol errors, you can simulate exceptions in two ways:

1. Use httpx_mock.add_exception(exception_instance) to raise a specific exception.
2. Raise an exception directly inside a callback function.

If no matching response is found for a request, pytest-httpx will raise an httpx.TimeoutException by default.

import httpx
import pytest
from pytest_httpx import HTTPXMock

def test_exception_raising(httpx_mock: HTTPXMock):
    httpx_mock.add_exception(httpx.ReadTimeout("Unable to read within timeout"))

    with httpx.Client() as client:
        with pytest.raises(httpx.ReadTimeout):
            client.get("https://test_url")

You can inspect the requests that were actually issued by the client using httpx_mock.get_requests() (returns all requests) or httpx_mock.get_request() (returns the single most recent request).

import httpx
from pytest_httpx import HTTPXMock

def test_many_requests(httpx_mock: HTTPXMock):
    httpx_mock.add_response()

    with httpx.Client() as client:
        response1 = client.get("https://test_url")
        response2 = client.get("https://test_url")

    requests = httpx_mock.get_requests()


def test_single_request(httpx_mock: HTTPXMock):
    httpx_mock.add_response()

    with httpx.Client() as client:
        response = client.get("https://test_url")

    request = httpx_mock.get_request()


def test_no_request(httpx_mock: HTTPXMock):
    assert not httpx_mock.get_request()