pytest-httpx

Warnings

• breaking Versions prior to 1.0.0 are subject to breaking changes without notice. Users should review the `CHANGELOG.md` when upgrading between minor versions, especially before 0.31.0 where significant behavioral changes occurred.
  Fix: Always consult the `CHANGELOG.md` on the GitHub repository when upgrading to understand potential breaking changes. Pay close attention to changes in assertion defaults and callback signatures.
• gotcha By default, `pytest-httpx` asserts that all issued HTTPX requests were matched by a registered response. If your test intentionally issues requests that are not meant to be mocked (e.g., to external services), this will cause a test failure.
  Fix: To disable this assertion for specific tests or modules, use the `pytest.mark.httpx_mock(assert_all_requests_were_expected=False)` marker. For selective mocking, consider the `should_mock` parameter.
• gotcha By default, `pytest-httpx` asserts that all registered responses were requested during test execution. If you register responses that are optional and might not be used in every test run, this will cause a test failure.
  Fix: To mark a specific response as optional, set `is_optional=True` when calling `add_response`. To disable this assertion globally for a test, use the `pytest.mark.httpx_mock(assert_all_responses_were_requested=False)` marker.
• breaking Prior to version `0.31.0`, the last registered matching response would be reused indefinitely. Since `0.31.0`, responses are no longer reused by default if all matching responses have already been sent, to help spot regressions where requests are issued more times than expected.
  Fix: If you require the old behavior where the last matching response is reused, use the `pytest.mark.httpx_mock(can_send_already_matched_responses=True)` marker.
• deprecated The `non_mocked_hosts` option for specifying hosts that should not be mocked has been removed.
  Fix: Use the `should_mock` parameter in `pytest.mark.httpx_mock` instead. This parameter expects a callable that takes an `httpx.Request` object and returns `True` if the request should be mocked, or `False` if it should pass through unmocked. Example: `pytest.mark.httpx_mock(should_mock=lambda request: 'my_local_test_host' not in request.url.host)`.
• breaking The expected return type for callbacks registered with `add_callback` changed significantly.
  Fix: Before `0.20.0`, callbacks were expected to return a tuple representing the HTTP response. As of `0.20.0` and later, callbacks are expected to return an `httpx.Response` instance directly.

Install

• pip install pytest-httpx Install stable version

Imports

• httpx_mock

  from pytest_httpx import httpx_mock

  The primary pytest fixture for mocking HTTPX requests.
• HTTPXMock

  from pytest_httpx import HTTPXMock

  Primarily used for type hinting the `httpx_mock` fixture.

Quickstart

This quickstart demonstrates how to use the `httpx_mock` fixture to intercept and provide mocked responses for both synchronous and asynchronous HTTPX requests within pytest. It shows how to add a JSON response for a GET request and a status code for a POST request.

import pytest
import httpx
from pytest_httpx import httpx_mock, HTTPXMock # HTTPXMock for type hinting

def test_sync_request_mocking(httpx_mock: HTTPXMock):
    httpx_mock.add_response(url="https://example.com/api/items", json={"data": ["item1", "item2"]})

    with httpx.Client() as client:
        response = client.get("https://example.com/api/items")

    assert response.status_code == 200
    assert response.json() == {"data": ["item1", "item2"]}

@pytest.mark.asyncio
async def test_async_request_mocking(httpx_mock: HTTPXMock):
    httpx_mock.add_response(url="https://example.com/api/async-items", status_code=201)

    async with httpx.AsyncClient() as client:
        response = await client.post("https://example.com/api/async-items", json={"name": "new item"})

    assert response.status_code == 201
    assert not response.content # No content for 201 by default