aiointercept

What it is and what it does

aiointercept is a testing library that mocks aiohttp HTTP requests by starting a real aiohttp.web server and routing client requests to it instead of replacing them with fake objects. Unlike pure mocking libraries, your code runs its full HTTP stack—serialization, header handling, content-type negotiation—but the remote endpoint is replaced with a local test server. You register responses by URL pattern and receive real aiohttp.web.Request objects in callbacks, letting you inspect what the client actually sent. It supports both direct URL redirection and transparent DNS interception for hardcoded URLs.

The library ships with a pytest plugin that runs a session-scoped server and provides the aiointercept_mock fixture, clearing registered handlers between tests to prevent leakage. It aims for API compatibility with aioresponses, making it a near drop-in replacement for existing test suites. Requires Python ≥3.10 and aiohttp ≥3.13.

Use it for:

• Test async code that makes HTTP requests without hitting real servers or mocking the socket layer
• Verify that your client correctly serializes headers, bodies, and query parameters through the full aiohttp stack
• Intercept and inspect requests in callbacks to assert on what the client actually sent
• Run integration tests with a session-scoped server via pytest fixture to avoid per-test startup overhead
• Migrate from aioresponses while keeping most of your test code unchanged

Worth the install?

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

Intercepts aiohttp client requests by routing them through a real test server, enabling HTTP testing without mocking at the socket layer.

Yes. It fills a real gap between pure mocking (fast but unrealistic) and hitting real servers (slow and fragile). Low install friction, no security issues, active maintenance, and MIT licensing make it a safe choice for async HTTP testing.

Install

aiointercept on PyPI

pip install aiointercept

uv add aiointercept

poetry add aiointercept

Installing aiointercept

Before you install

Low friction: pure Python wheel with three stable runtime dependencies (aiohttp, multidict, yarl). Actively maintained with recent release and commits through 2026-08-12.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open and closed projects with minimal attribution requirements.

Quickstart

pip install aiointercept

import aiohttp
from aiointercept import aiointercept

async with aiointercept() as m:
    m.get(f"{m.server_url}/users", payload=[{"id": 1}])
    async with aiohttp.ClientSession() as session:
        resp = await session.get(f"{m.server_url}/users")
        assert await resp.json() == [{"id": 1}]

Requires Python ≥3.10 and aiohttp ≥3.13

Verify before relying

• Whether pytest-asyncio is required or optional for the aiointercept_mock fixture
• Performance characteristics when intercepting high-volume or large-payload requests
• Compatibility with aiohttp versions older than 3.13

Package facts

Evidence: aiointercept-0.1.9-py3-none-any.whl

Keywords: aiohttp, aioresponses, asyncio, mock, pytest, testing

Tags

More Testing packages