pytest-aiohttp

pytest-aiohttp is the official aio-libs pytest plugin that provides ready-made fixtures for spinning up aiohttp test servers and clients inside your test suite. Built on top of pytest-asyncio, it lets you write plain async test functions that receive an aiohttp_client or aiohttp_server fixture and exercise real request/response flows against your application.

The plugin handles the tedious parts of async web testing: it starts test servers on ephemeral ports, wires up clients, and tears everything down automatically after each test. It supports pytest-asyncio’s auto and strict modes and smooths over legacy configuration, so integrating it into an existing aiohttp project is a matter of installing the package and adding a single configuration line.

What You Get

• aiohttp_client and aiohttp_server factory fixtures for exercising your app in tests
• Automatic startup on ephemeral ports and cleanup of servers and clients after each test
• Compatibility with pytest-asyncio auto and strict modes, with legacy mode handling
• Typed Protocol interfaces for the fixtures so calls are checked by type checkers

Common Use Cases

• Writing integration tests that send real HTTP requests to an aiohttp application
• Testing WebSocket and streaming handlers against a live test server
• Adding async endpoint tests to an existing aiohttp project with minimal setup

Under The Hood

Architecture

The whole plugin lives in pytest_aiohttp/plugin.py. A tryfirst pytest_configure hook reconciles the deprecated legacy asyncio mode into auto, and the core value is a set of pytest_asyncio fixtures: aiohttp_server, aiohttp_client, and aiohttp_raw_server. Each fixture is a factory (a callable returning an awaitable) that appends created servers/clients to a local list and closes them in a finally block after the test yields, giving deterministic cleanup. Typed Protocol classes (AiohttpClient, AiohttpServer, AiohttpRawServer) with overloads describe the factory call signatures.

Tech Stack

Pure Python, 100 percent of the repo. It depends on aiohttp (test_utils, web) and pytest-asyncio, and targets modern Python with PEP 604 unions and collections.abc typing. Packaging is via setup.py; releases are published on GitHub and PyPI under the aio-libs org.

Code Quality

The code is compact, fully type-annotated, and uses Protocol/overload for precise fixture typing. A tests directory (test_fixtures.py, test_switch_mode.py) covers both the fixtures and the mode-switching logic. As part of aio-libs it follows the org’s mature CI and review conventions.

API Design

The surface is deliberately tiny: install, add asyncio_mode = auto, then request a fixture in a test. The factory pattern keeps usage idiomatic to pytest, and README examples get a new user productive in minutes, so the learning curve is low for anyone already using pytest.