Python Testing Patterns

TDD Workflow for Python

RED     → Write a failing test first (pytest.raises or assertion failure expected)
GREEN   → Write minimal code to make the test pass
REFACTOR → Improve code while keeping tests green
REPEAT  → Continue with next requirement

Use agent-workflow:python-tdd-guide for step-by-step TDD guidance during implementation.

Test Structure

tests/
├── conftest.py          # shared fixtures (session/module/function scope)
├── unit/
│   ├── test_user_service.py
│   └── test_order_service.py
└── integration/
    ├── test_user_api.py
    └── test_order_api.py

Naming rules:

• Files: test_<module>.py
• Functions: test_<behaviour>_<condition> — e.g. test_get_user_not_found
• Classes (optional grouping): class TestUserService:

Run all tests: pytest — Run single file: pytest tests/unit/test_user_service.py

Test Layering

Default to the narrowest layer that covers the behaviour. Reserve integration tests for flows that cannot be verified in isolation.

Fixtures

Define shared state in conftest.py. Choose the narrowest scope that works.

# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from myapp.main import app
from myapp.database import Base, get_db

@pytest.fixture(scope="session")
def db_engine():
    engine = create_engine("sqlite:///:memory:")
    Base.metadata.create_all(engine)
    yield engine
    Base.metadata.drop_all(engine)

@pytest.fixture
def db_session(db_engine):
    Session = sessionmaker(bind=db_engine)
    session = Session()
    yield session
    session.rollback()
    session.close()

@pytest.fixture
def client(db_session):
    app.dependency_overrides[get_db] = lambda: db_session
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()

Scope guide: session for expensive setup (DB engine, containers), function (default) for anything that mutates state.

Mocking

Prefer unittest.mock.patch as a decorator or context manager. Use pytest-mock's mocker fixture as an alternative.

from unittest.mock import patch, MagicMock, AsyncMock

# Patch at the import location of the caller, not the definition
def test_send_notification_called(user_service):
    with patch("myapp.services.user.notification_client.send") as mock_send:
        user_service.activate(user_id=1)
        mock_send.assert_called_once_with(user_id=1, event="activated")

# Async mock for coroutines
async def test_fetch_user(user_service):
    mock_repo = AsyncMock()
    mock_repo.get_by_id.return_value = User(id=1, name="alice")
    user_service.repo = mock_repo

    result = await user_service.get(1)
    assert result.name == "alice"

# pytest-mock alternative
def test_send_notification_mocker(mocker, user_service):
    mock_send = mocker.patch("myapp.services.user.notification_client.send")
    user_service.activate(user_id=1)
    mock_send.assert_called_once()

Use AsyncMock for any coroutine. Use MagicMock for synchronous callables.

Coverage

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

# Generate HTML report
pytest --cov=src --cov-report=html
# Open: htmlcov/index.html

Target: overall ≥ 80%. Focus on service and business logic layers. Coverage does not substitute for meaningful assertions — a test that calls code without asserting anything inflates coverage without value.

Anti-patterns