Build a FastAPI App with Test-Driven Development (TDD): A Beginner’s Guide

🌟 What You’ll Learn

• What is FastAPI?
• What is Test-Driven Development (TDD)?
• Setting up your environment
• Writing your first test
• Creating a FastAPI endpoint
• Running tests and iterating
• Final thoughts

🤔 What is FastAPI?

FastAPI is a modern, fast (high-performance) web framework for building APIs with Python 3.7+ using standard Python type hints.

• Super fast thanks to Starlette and Pydantic
• Automatic OpenAPI docs
• Great developer experience

🧪 What is Test-Driven Development (TDD)?

Test-Driven Development (TDD) is a software development approach where you write tests before writing the actual code. The cycle usually looks like this:

1. Write a test (that fails)
2. Write just enough code to make the test pass
3. Refactor and clean up the code
4. Repeat 🔁

🛠️ Setting Up the Project

Let’s build a simple To-Do API using TDD with FastAPI.

📁 Project Structure

fastapi-todo-tdd/
├── app/
│   ├── __init__.py
│   └── main.py
├── tests/
│   └── test_main.py
├── requirements.txt
└── README.md

✅ Step 1: Install Required Packages

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install fastapi uvicorn pytest httpx

Add these to requirements.txt:

fastapi
uvicorn
pytest
httpx

🧪 Step 2: Write Your First Test

Create a file tests/test_main.py.

# tests/test_main.py

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

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Welcome to the ToDo API"}

We haven't even created the / endpoint yet. That’s the TDD way!

🖥️ Step 3: Create the FastAPI App

Create the file app/main.py.

# app/main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Welcome to the ToDo API"}

🧪 Step 4: Run the Test

pytest

✅ You should see:

1 passed in 0.XXs

📌 Step 5: Add a New Feature with TDD

Let’s allow users to add a to-do item.

🔍 Write the Failing Test First

Update tests/test_main.py:

def test_create_todo():
    response = client.post("/todos", json={"title": "Learn FastAPI"})
    assert response.status_code == 201
    assert response.json() == {
        "id": 1,
        "title": "Learn FastAPI"
    }

🔴 Run the test now — it will fail (because the endpoint doesn’t exist yet). That’s expected!

✅ Step 6: Write the Endpoint

Update app/main.py:

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()
todos = []  # In-memory storage
id_counter = 1

class ToDo(BaseModel):
    title: str

class ToDoResponse(ToDo):
    id: int

@app.get("/")
def read_root():
    return {"message": "Welcome to the ToDo API"}

@app.post("/todos", status_code=status.HTTP_201_CREATED, response_model=ToDoResponse)
def create_todo(todo: ToDo):
    global id_counter
    new_todo = {"id": id_counter, "title": todo.title}
    todos.append(new_todo)
    id_counter += 1
    return new_todo

✅ Step 7: Run Tests Again

pytest

✅ Both tests should now pass:

2 passed in 0.XXs

Boom! You've just built a basic API endpoint using Test-Driven Development.

🧹 Optional: Add More Features

You can follow the same cycle for:

• Listing all todos
• Deleting a todo
• Marking a todo as complete

Each time, write a failing test, write the minimum code, then refactor.

📚 Final Thoughts

Using TDD with FastAPI:

• Helps you write clean, testable code
• Gives you confidence while refactoring
• Makes onboarding easier for teams

🚀 Next Steps

• Add a database (SQLite or PostgreSQL)
• Use SQLAlchemy or Tortoise ORM
• Use pytest fixtures for setup/teardown
• Deploy using Docker or Heroku

💬 Got Questions?

Drop your comments or questions below. Happy coding!