Skip to content

asyncly

A tiny async HTTP client and a real aiohttp mock server for testing your integrations — built on aiohttp.

asyncly is two small, composable pieces:

  • HTTP client

    BaseHttpClient — a thin, typed base class for writing API clients. Map status codes to response handlers, parse into Pydantic / msgspec / JSON, set flexible timeouts, and route through a proxy.

    HTTP client guide

  • Mock server

    srvmocker runs a real aiohttp.TestServer inside your test loop — not a transport patch. Simulate upstreams, swap responses per test, and assert exactly what your client sent.

    Mock server guide

Why a real server instead of patching?

Transport-patching mocks (aioresponses, respx) are fast but never touch a socket — they miss real timeouts, header auto-injection, connection handling, and serialization quirks. asyncly serves a genuine aiohttp server in the same event loop, so your client exercises the real network stack.

See Testing strategies for the full comparison.

Features

  • Typed client base with per-status response handlers (JSON, Pydantic, msgspec).
  • Real mock server via start_service with dynamic, per-test responses.
  • Request matching — route by JSON body, headers, or query.
  • Assertions on recorded request history.
  • Proxy testing — a forwarding mock proxy with Proxy-Authorization validation.
  • TLS, msgpack/TOML/YAML responses, and metrics (Prometheus, OpenTelemetry).
  • A pytest plugin with ready-made fixtures.

Get started

pip install asyncly

Then jump into the Quickstart.