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

Mocks external HTTP/HTTPS services for asyncio-based tests by intercepting aiohttp requests and returning predefined responses without making real network calls.

Yes, if you write asyncio tests with aiohttp. It has low install friction, no known vulnerabilities, permissive licensing, and is stable and widely used despite dormant maintenance. The trade-off: the last release was over 945 days ago, so if you need fixes for new Python or aiohttp versions, you may need to fork or wait for a maintainer response. For active projects on current Python (3.7–3.12), it works as-is.

Install

aresponses on PyPI

pip install aresponses

uv add aresponses

poetry add aresponses

Installing aresponses

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).

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()

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.

Verify before relying

• Whether the dormant maintenance status (945 days since last release) poses a risk for future Python or aiohttp compatibility.
• Performance characteristics when mocking high-volume or complex request/response patterns.
• Compatibility with pytest-asyncio versions beyond what the fact sheet specifies.

Package facts

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

Keywords: asyncio, testing, responses

Tags

More Testing packages