aresponses

What it is and what it does

aresponses is a test fixture and mock server for asyncio applications that use aiohttp. It intercepts HTTP and HTTPS requests made by aiohttp.ClientSession and returns predefined responses without touching the network. You define routes using pattern matching (exact strings or regular expressions) on host, path, method, and body, then attach responses—plain text, JSON dicts, custom Response objects, or callable handlers. When your test code makes a request, aresponses matches it to the first registered route, returns the response, and removes that route from the table.

The package is designed for pytest integration and requires explicit assertions at the end of each test to verify that routes were called in order, all routes were used, and no unmatched requests occurred. It supports regex patterns for flexible matching, repeated routes via the repeat parameter, JSON responses as a convenience, custom handler functions, and a passthrough mode to let specific requests reach the real network. Version 3.0.0 updated to use asyncio.get_running_loop() instead of the deprecated event_loop fixture pattern.

Use it for

• Unit test an async client library or service that calls external APIs without making real HTTP requests.
• Simulate error responses (500, timeouts, malformed JSON) to test error handling in async code.
• Mock multiple external services in a single test by registering different routes for different hosts.
• Verify that your async code calls external APIs in the correct order with the correct parameters.
• Test HTTPS requests by transparently converting them to HTTP mocks without certificate setup.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

aresponses on PyPI

Before you install

Low friction: pure Python wheel with only two runtime dependencies (pytest-asyncio and aiohttp). Maintenance is dormant—last release was 2024-01-12, over 945 days ago, though the repository remains active and the package is widely used (115539 monthly downloads).

Requires pytest-asyncio to be installed and your test function decorated with @pytest.mark.asyncio; version 3.0.0 uses asyncio.get_running_loop() and may not work with older event loop patterns.

License in practice

Licensed under MIT (permissive), so you can use it freely in commercial and private projects with minimal restrictions.

Quickstart

pip install aresponses

import aresponses
import aiohttp
import pytest

@pytest.mark.asyncio
async def test_mock(aresponses):
    aresponses.add("example.com", "/api", "GET", response="OK")
    async with aiohttp.ClientSession() as session:
        async with session.get("http://example.com/api") as resp:
            assert await resp.text() == "OK"
    aresponses.assert_plan_strictly_followed()

Package facts

Evidence: aresponses-3.0.0-py3-none-any.whl

Tags

More Testing packages

See also aioresponses · aiosonic · aiointercept · sanic-testing · pytest-responses · urllib3-mock · responses · pytest-aiohttp · looptime · asyncmock