---
id: aiointercept
version: "0.1.9"
license: MIT
license_treatment: permissive
maintenance: active
---

# aiointercept — aiohttp mock library that routes requests through a real test server

License: permissive · Maintenance: active · Downloads: 109.2K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 109.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

aiohttp mock testing, async http request interception, aiohttp test server, asyncio http mocking, aiohttp integration testing, mock aiohttp requests, aiohttp testing library, aiohttp, async-testing, pytest-plugin

[View on SkillFed](https://skillfed.io/packages/aiointercept) · [View on PyPI](https://pypi.org/project/aiointercept/)