Async test patterns in FastAPI

Introduction

Async test patterns help you check if your FastAPI app works well with asynchronous code. They make sure your async functions run correctly and return expected results.

When testing API endpoints that use async functions

When you want to verify database calls made with async libraries

When your app uses async background tasks and you want to test them

When you want to ensure your async code handles errors properly

When you want to test concurrency behavior in your FastAPI app

Syntax

FastAPI

import pytest
from httpx import AsyncClient
from fastapi import FastAPI

@pytest.mark.asyncio
async def test_async_endpoint():
    app = FastAPI()

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

    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/hello")
        assert response.status_code == 200
        assert response.json() == {"message": "Hello, async!"}

Use pytest.mark.asyncio to mark async test functions.

Use AsyncClient from httpx to call async FastAPI endpoints in tests.

Examples

This tests a simple async GET endpoint returning a JSON response.

FastAPI

import pytest
from fastapi import FastAPI
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_simple_async():
    app = FastAPI()

    @app.get("/ping")
    async def ping():
        return {"ping": "pong"}

    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/ping")
        assert response.status_code == 200
        assert response.json() == {"ping": "pong"}

This tests an async endpoint with query parameters and checks the sum result.

FastAPI

import pytest
from fastapi import FastAPI
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_async_with_query():
    app = FastAPI()

    @app.get("/add")
    async def add(x: int, y: int):
        return {"result": x + y}

    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/add", params={"x": 3, "y": 4})
        assert response.status_code == 200
        assert response.json() == {"result": 7}

This tests how async endpoints handle errors and return proper HTTP status codes.

FastAPI

import pytest
from fastapi import FastAPI, HTTPException
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_async_error():
    app = FastAPI()

    @app.get("/error")
    async def error():
        raise HTTPException(status_code=400, detail="Bad request")

    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/error")
        assert response.status_code == 400
        assert response.json()["detail"] == "Bad request"

Sample Program

This test checks an async endpoint that greets a user by name. It verifies the status code and JSON response.

FastAPI

import pytest
from fastapi import FastAPI
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_async_greeting():
    app = FastAPI()

    @app.get("/greet/{name}")
    async def greet(name: str):
        return {"greeting": f"Hello, {name}!"}

    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/greet/Alice")
        assert response.status_code == 200
        assert response.json() == {"greeting": "Hello, Alice!"}

Important Notes

Always use async def for test functions testing async code.

Use AsyncClient to simulate HTTP calls to your FastAPI app asynchronously.

Mark tests with @pytest.mark.asyncio so pytest knows to run them asynchronously.

Summary

Async test patterns let you test FastAPI async endpoints easily.

Use AsyncClient and pytest.mark.asyncio for async tests.

Check status codes and JSON responses to confirm your async code works.