Test FastAPI Endpoints with pytest and TestClient

Building a FastAPI application is fast. But how do you know it works correctly? You must test it. Testing ensures your API is reliable. It catches bugs before users do. This guide shows you how.

We will use pytest and FastAPI's TestClient. This combination is powerful. It lets you simulate HTTP requests. You can test endpoints without a live server. Let's dive into writing clean, effective tests.

Why Test Your FastAPI API?

Testing is not optional. It is a core part of development. It verifies your code logic. Tests protect against regressions. They make refactoring safe. Automated tests save time.

For APIs, you test routes, status codes, and responses. You also test error handling. FastAPI and pytest make this straightforward. You get fast feedback on your code's health.

Setting Up Your Testing Environment

First, ensure you have a FastAPI project. If you're new, check our FastAPI Tutorial: Build Your First Python REST API. You need to install testing dependencies.

Use pip to install pytest and httpx. The TestClient comes from httpx.

pip install pytest httpx

Your project structure should be clear. Keep tests in a separate directory. A common pattern is a `tests` folder at the root.

Creating a Simple FastAPI App to Test

Let's create a basic app. We will write tests for it. This app has a GET and a POST endpoint. It uses a Pydantic model for data validation.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

This is a typical FastAPI application. For more on data validation, see FastAPI Validation with Pydantic Models.

Writing Your First Test with TestClient

Now, create a test file. Name it `test_main.py` inside a `tests` folder. Import the necessary modules.

The TestClient is your main tool. You pass your FastAPI app to it. Then you can call methods like .get() and .post().

# tests/test_main.py
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"Hello": "World"}

def test_read_item():
    response = client.get("/items/42?q=test")
    assert response.status_code == 200
    assert response.json() == {"item_id": 42, "q": "test"}

Run the tests using the pytest command in your terminal.

pytest

You should see passing tests. The output confirms your endpoints work as expected.

Testing POST Endpoints and Request Bodies

Testing POST endpoints is crucial. You send JSON data and check the response. Use the .post() method with a `json` parameter.

def test_create_item():
    item_data = {"name": "Laptop", "price": 999.99}
    response = client.post("/items/", json=item_data)
    assert response.status_code == 200
    json_response = response.json()
    assert json_response["item_name"] == "Laptop"
    assert json_response["item_price"] == 999.99

This test sends a JSON payload. FastAPI automatically validates it using the Pydantic model. The test asserts the response matches.

Testing Error Responses and Status Codes

Good tests also check for errors. What happens for invalid input? Test for 422 Unprocessable Entity or 404 Not Found.

def test_create_item_invalid():
    # Missing required 'price' field
    invalid_data = {"name": "Laptop"}
    response = client.post("/items/", json=invalid_data)
    assert response.status_code == 422  # Validation error

def test_read_item_not_found():
    # Assuming your logic might handle non-existent items
    response = client.get("/items/999")
    # You might expect a 404 if you add that logic
    assert response.status_code == 200  # Or 404 based on your app

Testing error paths is as important as testing success. It ensures your API is robust.

Using Fixtures for Efficient Testing

pytest fixtures help you set up reusable state. A common fixture is the TestClient itself. This keeps your code DRY.

import pytest
from fastapi.testclient import TestClient
from main import app

@pytest.fixture
def client():
    with TestClient(app) as c:
        yield c

def test_with_fixture(client):
    response = client.get("/")
    assert response.status_code == 200

The client fixture is available to all test functions. It is created fresh for each test. This is a clean pattern.

Testing Endpoints with Dependencies

Many APIs use dependencies like database sessions or authentication. You can override them during tests. Use FastAPI's dependency overrides.

Imagine an endpoint needing a current user. You can provide a mock user for testing. This isolates the endpoint logic.

from fastapi import Depends
from main import app

def get_current_user():
    # Real implementation gets user from JWT
    return {"username": "real_user"}

@app.get("/protected")
def protected_route(user: dict = Depends(get_current_user)):
    return {"user": user}

# In your test file
def test_protected_route(client):
    # Override the dependency
    def override_get_user():
        return {"username": "test_user"}

    app.dependency_overrides[get_current_user] = override_get_user
    response = client.get("/protected")
    assert response.status_code == 200
    assert response.json()["user"]["username"] == "test_user"
    # Clear the override after test
    app.dependency_overrides.clear()

This technique is powerful for complex applications. For a full guide on auth, see FastAPI JWT Authentication Python Tutorial.

Best Practices for FastAPI Testing

Follow these tips for effective tests. Keep tests independent. One test should not affect another. Use clear, descriptive test names.

Test both happy paths and edge cases. Mock external services like databases or APIs. Keep your test suite fast. Run it often during development.

Structure your tests to mirror your app structure. This makes them easy to navigate. Use fixtures for common setup tasks.

Integrating Tests into Your Workflow

Tests should run automatically. Use a CI/CD pipeline. Every code push can trigger your test suite. This ensures quality.

When you are ready to deploy, having a solid test suite gives confidence. For deployment strategies, read Deploy FastAPI with Docker for Production.

Testing is a continuous process. Write tests as you develop new features. Refactor tests when you refactor code.

Conclusion

Testing FastAPI endpoints is essential. Using pytest and TestClient makes it simple. You can test all aspects of your API.

Start with basic status code checks. Move to testing request bodies and error handling. Use fixtures and dependency overrides for advanced scenarios.

A well-tested API is a reliable API. It builds trust with your users. It makes your development process smoother. Begin writing tests for your FastAPI projects today.