aioresponses

What it is and what it does

aioresponses is a testing helper that intercepts and mocks HTTP requests made by aiohttp's ClientSession, letting you test asynchronous code without hitting real servers. It works as a decorator or context manager and lets you specify mock responses by URL, including status codes, JSON payloads, headers, and exceptions. You can also use regex patterns to match URLs, repeat responses for retry testing, simulate redirects, or pass through to real servers selectively.

The package fills a gap in the async testing ecosystem—while synchronous HTTP libraries have many mocking options, aioresponses makes it straightforward to test async code that uses aiohttp. It depends on aiohttp and packaging, both common in Python projects. The library is actively maintained and has been stable since its early releases.

Use it for:

• Test async functions that call external APIs without making real network requests
• Verify retry logic by mocking the same URL to return different status codes in sequence
• Mock JSON API responses to test data parsing in async code
• Simulate HTTP errors and exceptions to test error handling in async workflows
• Test redirect handling by mocking Location headers with 3xx status codes

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Mocks HTTP requests made by aiohttp's ClientSession for testing asynchronous code, supporting GET, POST, PUT, PATCH, DELETE, and OPTIONS methods with customizable status codes, bodies, headers, and JSON payloads.

Yes. aioresponses is a focused, well-maintained tool for a common testing need in async Python. It has no known vulnerabilities, low install friction, a permissive license, and active development. Install it if you write tests for code using aiohttp.

Install

aioresponses on PyPI

pip install aioresponses

uv add aioresponses

poetry add aioresponses

Installing aioresponses

Before you install

Low friction install with just two runtime dependencies (packaging and aiohttp). Actively maintained with a recent release; repository shows steady activity and moderate community engagement.

License in practice

Permissive license allows unrestricted use in commercial and open-source projects without copyleft obligations.

Quickstart

pip install aioresponses

from aioresponses import aioresponses
import aiohttp
import asyncio

@aioresponses()
def test_example(mocked):
    mocked.get('http://example.com', status=200, body='test')
    session = aiohttp.ClientSession()
    resp = asyncio.run(session.get('http://example.com'))
    assert resp.status == 200

Requires Python 3.10+ and aiohttp>=3.8,<4.0

Verify before relying

• Whether the package supports Python 3.14 in practice (listed as classifier but may be aspirational)

Package facts

Evidence: aioresponses-0.7.9-py2.py3-none-any.whl

Tags

More WWW/HTTP packages