respx
HTTP mocking library for httpx — intercepts httpx requests in tests and returns mock responses. respx features: respx.mock context manager, @respx.mock decorator for test functions, route matching by URL/method/headers/content, httpx.Response builder for mock responses, side_effect functions for dynamic responses, route patterns with wildcards, assert_all_called/assert_all_mocked, async support (works with pytest-asyncio), base_url mocking, and call inspection. The httpx equivalent of responses (for requests) or aioresponses (for aiohttp).
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Test-only library — no network access, no security concerns. Mock responses should not contain real API credentials. respx assert_all_mocked ensures no real network calls leak from agent tests to external APIs.
⚡ Reliability
Best When
Your async Python agent uses httpx for HTTP calls (FastAPI test client, async agents) and you need mock HTTP responses in pytest tests — respx provides clean httpx-native mocking with async support.
Avoid When
Your agent uses requests library (use responses) or aiohttp (use aioresponses).
Use Cases
- • Agent httpx API mocking — with respx.mock: respx.get('https://api.openai.com/v1/chat/completions').mock(return_value=httpx.Response(200, json=mock_completion)); result = await agent.call_llm(prompt) — mock LLM API in async agent tests
- • Agent tool HTTP mocking — @respx.mock; def test_web_search(): respx.get('https://api.search.com/search', params={'q': 'test'}).mock(return_value=httpx.Response(200, json=search_results)); results = agent.search('test'); assert len(results) == 5
- • Agent error handling tests — respx.get('https://api.example.com/data').mock(return_value=httpx.Response(429, json={'error': 'rate_limited'})); with pytest.raises(AgentRateLimitError): agent.fetch_data() — test agent HTTP error handling
- • Dynamic mock responses — respx.post('https://api.llm.com/chat').mock(side_effect=lambda req: httpx.Response(200, json={'response': f'Mock: {req.content}'})) — dynamic response based on request; agent test validates request content
- • Agent mock assertion — route = respx.post('https://api.tool.com/execute'); agent.execute_tool('search', params); assert route.called; assert route.call_count == 1; assert json.loads(route.calls[0].request.content) == {'tool': 'search', 'params': params} — verify agent made correct API call
Not For
- • requests library mocking — respx only intercepts httpx; for requests-based code use responses library
- • aiohttp mocking — respx is httpx-specific; for aiohttp use aioresponses
- • VCR-style cassette recording — respx doesn't record/replay; for cassette-based mocking use VCR with httpx adapter
Interface
Authentication
No auth — test HTTP mocking library.
Pricing
respx is BSD licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ respx blocks ALL httpx requests by default — respx.mock context raises AllMockedError for any unmocked URL; agent tests making incidental httpx calls (health checks, metrics) must mock all URLs; use respx.mock(assert_all_mocked=False) to allow unmocked requests through for agent tests with side-effect HTTP
- ⚠ Route order matters for overlapping patterns — respx matches routes in registration order; respx.get(re.compile('.*')) before specific routes matches everything; agent tests with wildcard fallback routes must register specific routes first; overlapping patterns produce unexpected mock responses
- ⚠ respx.mock as context manager vs decorator behave differently — @respx.mock resets routes between test functions; with respx.mock: creates new scope but outer routes may leak; agent test fixtures using context manager approach may have route pollution between tests; use @respx.mock decorator on test functions for cleanest isolation
- ⚠ side_effect functions must return httpx.Response — respx side_effect=lambda req: {'json': 'data'} raises TypeError; must return httpx.Response(200, json={'data': 'value'}); agent tests using side_effect for dynamic responses must build complete httpx.Response objects
- ⚠ Async agent code requires @pytest.mark.asyncio with respx — async def test_agent(): with respx.mock: ... needs @pytest.mark.asyncio (pytest-asyncio) and async respx.mock; agent async tests without asyncio mark run sync context and miss async intercepts; combine pytest-asyncio and respx correctly
- ⚠ respx doesn't mock httpx.Client transport directly — respx intercepts at transport level; if agent code bypasses transport (e.g., mounts custom transport), respx may not intercept; agent code using custom mTLS or proxy transports needs explicit respx transport mock setup
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for respx.
Scores are editorial opinions as of 2026-03-06.