{"id":1870,"library":"pytest-httpx","title":"pytest-httpx","description":"pytest-httpx is a pytest fixture that provides a convenient way to mock HTTPX requests within test cases. It supports both synchronous and asynchronous HTTPX requests, allowing developers to define custom responses, status codes, headers, and simulate various HTTP conditions without making actual network calls. The library is currently at version 0.36.0 and is considered stable, with version 1.0.0 planned for release once HTTPX itself reaches 1.0.0.","status":"active","version":"0.36.0","language":"en","source_language":"en","source_url":"https://github.com/Colin-b/pytest_httpx","tags":["pytest","httpx","testing","mocking","http","asyncio"],"install":[{"cmd":"pip install pytest-httpx","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client library that pytest-httpx mocks. Requires >=0.28.","package":"httpx","optional":false},{"reason":"Testing framework that pytest-httpx extends. Requires >=3.10 (for Python compatibility) and implicitly a modern pytest version (e.g., >=5.4.0 mentioned in older changelogs).","package":"pytest","optional":false},{"reason":"Required for asynchronous test functions if not using pytest's native async support.","package":"pytest-asyncio","optional":true}],"imports":[{"note":"The primary pytest fixture for mocking HTTPX requests.","symbol":"httpx_mock","correct":"from pytest_httpx import httpx_mock"},{"note":"Primarily used for type hinting the `httpx_mock` fixture.","symbol":"HTTPXMock","correct":"from pytest_httpx import HTTPXMock"}],"quickstart":{"code":"import pytest\nimport httpx\nfrom pytest_httpx import httpx_mock, HTTPXMock # HTTPXMock for type hinting\n\ndef test_sync_request_mocking(httpx_mock: HTTPXMock):\n    httpx_mock.add_response(url=\"https://example.com/api/items\", json={\"data\": [\"item1\", \"item2\"]})\n\n    with httpx.Client() as client:\n        response = client.get(\"https://example.com/api/items\")\n\n    assert response.status_code == 200\n    assert response.json() == {\"data\": [\"item1\", \"item2\"]}\n\n@pytest.mark.asyncio\nasync def test_async_request_mocking(httpx_mock: HTTPXMock):\n    httpx_mock.add_response(url=\"https://example.com/api/async-items\", status_code=201)\n\n    async with httpx.AsyncClient() as client:\n        response = await client.post(\"https://example.com/api/async-items\", json={\"name\": \"new item\"})\n\n    assert response.status_code == 201\n    assert not response.content # No content for 201 by default","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.31.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.31.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.31.0"},{"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)`.","message":"The `non_mocked_hosts` option for specifying hosts that should not be mocked has been removed.","severity":"deprecated","affected_versions":"<0.31.0 (removed in 0.31.0)"},{"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.","message":"The expected return type for callbacks registered with `add_callback` changed significantly.","severity":"breaking","affected_versions":"<0.20.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}