Testing Async Endpoints with Pytest and httpx

You’ve built a beautiful FastAPI app with async endpoints that hum along in production — but how do you know they actually work under the hood? Testing async endpoints with pytest and httpx is the safety net that catches regressions before your users do. In this lesson, you’ll move beyond curl and learn a repeatable, fast, and deterministic way to verify every route, status code, and response payload — no live server required.

The Problem This Lesson Solves

Manually testing endpoints is slow, error-prone, and impossible to scale. You start the server, open a browser or terminal, type a URL, and eyeball the JSON. That works for a demo, but the moment you refactor a dependency or change a response model, you’re left wondering: Did I just break something?

Automated tests solve that. But testing async endpoints introduces a subtle challenge: your FastAPI app uses async def for concurrency, and your test runner needs to match that style. If you write tests the same way you would for a synchronous Flask app, you’ll hit a wall of RuntimeErrors and missing event loops.

This lesson gives you a proven pattern using pytest and httpx — the same HTTP client FastAPI itself uses under the hood — to test async endpoints cleanly and quickly. You’ll learn to simulate real requests without spinning up a server, assert on responses and errors, and keep your tests fast enough to run on every commit.

Core Concept / Mental Model

Think of testing an async endpoint as a restaurant kitchen inspection. Your FastAPI app is the kitchen; the endpoint is a specific dish. An inspector (the test) walks in, orders the dish from the menu (sends an HTTP request), and checks that what comes out matches the recipe (the response).

The key tool here is httpx’s AsyncClient. It lets you send real HTTP requests to your app in-process — no network socket, no uvicorn server. Instead, FastAPI’s TestClient (which wraps httpx) talks directly to your ASGI app, bypassing the network stack. This makes tests deterministic, fast, and isolated.

Here’s the mental model in one line: pytest provides the structure, httpx provides the HTTP engine, and FastAPI’s dependency overrides give you control.

Definitions You’ll Need

• ASGI — Asynchronous Server Gateway Interface; the protocol FastAPI uses to talk to servers like uvicorn. httpx can speak ASGI directly.
• Async test client — An httpx AsyncClient that sends requests to your ASGI app without a live server.
• Dependency override — A FastAPI feature that replaces a dependency (like a database session) during testing.

How It Works Step by Step

Testing async endpoints isn’t magic — it’s a predictable sequence of steps. Here’s the cause-and-effect flow:

1. Define your FastAPI app with an async endpoint (e.g., async def get_item()).
2. Create an httpx AsyncClient with transport=httpx.ASGITransport(app=app) and a base URL like http://test.
3. Use async with to open the client — this manages the request lifecycle.
4. Send a request with await client.get("/items/1").
5. Assert on the response — status code, JSON body, headers, etc.
6. Run with pytest using pytest.mark.anyio or pytest.mark.asyncio (depending on your ecosystem).

Because the client runs entirely in-process, there’s no port conflicts, no background server, and tests run in milliseconds.

Why async with?

AsyncClient is an async context manager. The async with block ensures the client closes its connections properly, even if an assertion fails — no leaked resources.

Hands-On Walkthrough

Let’s build a minimal FastAPI app and test it. Create a new directory, then a file app.py:

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, async world!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id < 1:
        raise HTTPException(status_code=400, detail="Invalid item ID")
    return {"item_id": item_id, "name": f"Item {item_id}"}

Now write the test file test_app.py:

import pytest
from httpx import AsyncClient, ASGITransport
from app import app

@pytest.mark.anyio
async def test_read_root():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        response = await ac.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, async world!"}

@pytest.mark.anyio
async def test_read_item_success():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        response = await ac.get("/items/5")
    assert response.status_code == 200
    assert response.json()["name"] == "Item 5"

@pytest.mark.anyio
async def test_read_item_invalid():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        response = await ac.get("/items/0")
    assert response.status_code == 400
    assert response.json()["detail"] == "Invalid item ID"

Run the tests with pytest. You’ll need pytest, pytest-anyio, httpx, and fastapi installed. Expected output:

$ pytest
============================= test session starts ==============================
collected 3 items

test_app.py ...                                                          [100%]

============================== 3 passed in 0.12s ===============================

Testing with Dependency Overrides

Real apps often use dependencies for databases or authentication. Override them in tests to isolate your endpoint logic:

from fastapi import Depends
from app import app

async def get_db_session():
    # Real DB connection (not used in tests)
    raise NotImplementedError

@app.get("/users/{user_id}")
async def get_user(user_id: int, db=Depends(get_db_session)):
    return {"id": user_id, "db_status": "connected"}

# In test file
async def override_get_db_session():
    return {"fake": "db"}

app.dependency_overrides[get_db_session] = override_get_db_session

@pytest.mark.anyio
async def test_get_user():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        response = await ac.get("/users/1")
    assert response.status_code == 200
    assert response.json()["db_status"] == "connected"

Pro tip: Restore app.dependency_overrides after each test (use a fixture) to avoid cross-test contamination.

Compare Options / When to Choose What

There are several ways to test FastAPI async endpoints. Here’s a comparison to guide your choice:

For testing async endpoints with pytest and httpx, the first option is the gold standard. It gives you full control and speed.

Troubleshooting & Edge Cases

Even with the right tools, you’ll hit snags. Here are the most common ones and how to fix them:

• RuntimeError: Task attached to a different loop — Usually caused by mixing sync and async code in the same test, or using an async client inside a sync test without the proper decorator. Solution: always mark your test as @pytest.mark.anyio (or @pytest.mark.asyncio) and keep all I/O inside the async function.
• ConnectionRefusedError when using httpx.AsyncClient with base_url — You’re trying to connect to a real server. You must pass transport=ASGITransport(app=app) and use base_url="http://test".
• Tests pass in isolation but fail when run together — Likely dependency_overrides leaking. Reset them in a fixture after each test.
• TypeError: An asyncio.Future, a coroutine or an awaitable is required — Your test function isn’t async, or you forgot await on the client call.
• Missing pytest.mark.anyio — If you use @pytest.mark.anyio, ensure pytest-anyio is installed. For pytest-asyncio, use @pytest.mark.asyncio and configure asyncio_mode="auto" in pyproject.toml or pytest.ini.

Pro tip: Always use a fresh AsyncClient per test (or per fixture) to avoid state leaks.

What You Learned & What’s Next

You now know the core idea behind testing async endpoints with pytest and httpx: use httpx’s AsyncClient with ASGITransport to send real HTTP requests to your FastAPI app without a server, and write async test functions with pytest markers. You can assert status codes, JSON bodies, and error responses, and override dependencies for clean isolation.

You completed a hands-on exercise that takes you from a bare endpoint to a passing test suite. You also understand the trade-offs between different testing approaches and can troubleshoot common pain points.

Next in the track, you’ll dive into advanced testing patterns — mocking external services and using fixtures to build a robust test suite that scales with your backend complexity. With this foundation, you’re ready to make testing an integral part of your FastAPI development workflow.

Now, go write a test for your own endpoint and watch your confidence (and code quality) grow.