Agent skill

FastAPI_Pytest_TDDHelper

Senior Backend Architect and Principal QA Engineer skill for Test-Driven Development (TDD) with FastAPI and Pytest. Provides high-performance testing blueprints prioritizing execution speed and memory efficiency. Use when: (1) Setting up pytest for FastAPI projects, (2) Writing tests following Red-Green-Refactor TDD cycle, (3) Creating high-performance conftest.py with async fixtures, (4) Implementing transaction rollback patterns for fast test isolation, (5) Using httpx.AsyncClient for async endpoint testing, (6) Validating responses with Pydantic models, (7) Creating factory fixtures and dependency overrides, (8) Optimizing test execution speed and parallelization. Applies to FastAPI v0.100+ and Pytest v8.0+.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/alijilani-dev/Claude/tree/main/skills/fastapi-pytest-tddhelper

SKILL.md

FastAPI Pytest TDD Helper

High-performance TDD blueprint for FastAPI projects.

Core Principles

Principle Implementation
Speed AsyncClient over TestClient (~20% faster)
Isolation Transaction rollback, not schema recreation
TDD Red-Green-Refactor cycle strictly
Validation Pydantic models, not just status codes

Quick Start

1. Install Dependencies

bash
pip install pytest pytest-asyncio httpx aiosqlite pytest-cov

2. Configure pytest (pyproject.toml)

toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
addopts = ["-v", "--tb=short", "-x"]

3. Create conftest.py

python
import pytest
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
from sqlalchemy.pool import NullPool
from app.main import app
from app.database import Base, get_db

@pytest.fixture(scope="session")
async def async_engine():
    engine = create_async_engine("sqlite+aiosqlite:///./test.db", poolclass=NullPool)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield engine
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)

@pytest.fixture(scope="function")
async def db_session(async_engine):
    async_session = async_sessionmaker(async_engine, class_=AsyncSession)
    async with async_session() as session:
        async with session.begin():
            yield session
            await session.rollback()  # Fast isolation!

@pytest.fixture
async def client(db_session):
    app.dependency_overrides[get_db] = lambda: db_session
    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
        yield ac
    app.dependency_overrides.clear()

TDD Workflow: Red-Green-Refactor

Step 1: RED - Write Failing Test

python
from pydantic import BaseModel

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float

async def test_create_item(client):
    response = await client.post("/items/", json={"name": "Widget", "price": 10.0})

    assert response.status_code == 201
    item = ItemResponse(**response.json())  # Validate shape!
    assert item.name == "Widget"

Run: pytest -x (fails - endpoint doesn't exist)

Step 2: GREEN - Minimal Implementation

python
@app.post("/items/", status_code=201, response_model=ItemResponse)
async def create_item(item: ItemCreate, db: Session = Depends(get_db)):
    db_item = Item(**item.model_dump())
    db.add(db_item)
    db.commit()
    return db_item

Run: pytest -x (passes)

Step 3: REFACTOR - Optimize

Improve code quality, run tests to verify nothing breaks.

Reference Documentation

Task Reference
conftest.py patterns, fixture scopes references/conftest-patterns.md
Red-Green-Refactor examples references/tdd-workflow.md
pyproject.toml, parallel execution references/pytest-optimization.md
Response validation with Pydantic references/pydantic-validation.md
CRUD tests, mocking, overrides references/testing-patterns.md

Assets

Template Description
assets/conftest_template.py Complete conftest.py ready to customize
assets/pyproject_template.toml Optimized pytest configuration

Performance Decisions

Why AsyncClient Over TestClient

python
# AVOID: Sync-to-async bridge overhead
from fastapi.testclient import TestClient
client = TestClient(app)

# USE: Native async, ~20% faster
from httpx import AsyncClient, ASGITransport
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
    response = await client.get("/")

Why Transaction Rollback Over Schema Recreation

Approach 100 tests 1000 tests
Schema recreation ~60s ~600s
Transaction rollback ~5s ~50s
python
# FAST: Rollback at end of each test
async with session.begin():
    yield session
    await session.rollback()

Fixture Scoping Strategy

Scope Use For Example
session Expensive setup DB engine, app instance
function Test isolation DB session with rollback

Common Commands

bash
# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=term-missing

# Run specific test
pytest tests/test_items.py::test_create_item -v

# Run excluding slow tests
pytest -m "not slow"

# Parallel execution
pytest -n auto

# Stop on first failure (TDD mode)
pytest -x

# Run failed tests first
pytest --ff

Parametrize Pattern

python
@pytest.mark.parametrize("name,price,status", [
    ("Valid", 10.0, 201),
    ("", 10.0, 422),      # Empty name
    ("Item", -5.0, 422),  # Negative price
])
async def test_create_item_validation(client, name, price, status):
    response = await client.post("/items/", json={"name": name, "price": price})
    assert response.status_code == status

Factory Fixture Pattern

python
@pytest.fixture
def item_factory(db_session):
    async def _create(name="Item", price=10.0, **kwargs):
        item = Item(name=name, price=price, **kwargs)
        db_session.add(item)
        await db_session.flush()
        return item
    return _create

async def test_get_item(client, item_factory):
    item = await item_factory(name="Widget")
    response = await client.get(f"/items/{item.id}")
    assert response.json()["name"] == "Widget"

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

alijilani-dev/Claude

docker-rocker

Production-grade Docker containerization for FastAPI, Pytest, SQLModel, and Pydantic projects. This skill should be used when users ask to dockerize FastAPI applications, create multi-stage Docker builds, optimize Docker images for Python APIs, set up CI/CD Docker pipelines, or deploy containerized Python web APIs with maximum performance and minimal image size.

0 0
Explore
alijilani-dev/Claude

fastapi-helper

FastAPI development assistant for building modern Python web APIs. Provides guidance on routing, request/response handling, dependency injection, authentication, middleware, WebSockets, testing, and Pydantic models. Use when: (1) Creating FastAPI applications or endpoints, (2) Implementing CRUD operations, (3) Setting up authentication/authorization, (4) Working with request parameters (path, query, body, headers, cookies, forms, files), (5) Configuring middleware or CORS, (6) Implementing WebSocket connections, (7) Writing tests for FastAPI apps, (8) Defining Pydantic models for validation.

0 0
Explore
alijilani-dev/Claude

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

0 0
Explore
alijilani-dev/Claude

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

0 0
Explore
alijilani-dev/Claude

cover-letter-generator

Generate tailored AI-focused cover letters using the PSI (Problem-Solution-Impact) methodology. Use when: (1) User wants to create cover letters for AI/ML job applications, (2) User provides a resume and wants LinkedIn job matching, (3) User asks for personalized cover letters based on job postings, (4) User mentions applying for AI Engineer, ML Engineer, or similar technical roles. Integrates market intelligence, LinkedIn research via Playwright, and professional writing standards.

0 0
Explore
alijilani-dev/Claude

skill-validator

Validates skills against production-level criteria with 9-category scoring. This skill should be used when reviewing, auditing, or improving skills to ensure quality standards. Evaluates structure, content, user interaction, documentation, domain standards, technical robustness, maintainability, zero-shot implementation, and reusability. Returns actionable validation report with scores and improvement recommendations.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results