Pytest Backend Testing Guidelines

Purpose

Complete guide for writing comprehensive tests for FastAPI backend applications using pytest, pytest-asyncio, and FastAPI TestClient. Emphasizes async testing, proper mocking, layered testing (repository → service → router), and achieving high test coverage.

When to Use This Skill

Writing new test files for backend code
Testing repositories, services, or API routes
Setting up test fixtures and mocks
Debugging failing tests
Improving test coverage
Writing async tests with pytest-asyncio
Testing database operations
Using FastAPI TestClient for route testing

Quick Start

New Test File Checklist

Creating tests for new code? Follow this checklist:

Create test file:
```
tests/unit/{domain}/test_{module}.py
```
Import pytest and pytest-asyncio
Set up necessary fixtures (session, client, etc.)
Use
```
@pytest.mark.asyncio
```
for async tests
Follow AAA pattern: Arrange, Act, Assert
Mock external dependencies
Test both success and error cases
Verify coverage meets 80% threshold
Use descriptive test names:
```
test_<what>_<when>_<expected>
```

Test Coverage Checklist

Ensuring good coverage? Check these:

Test all public methods/functions
Test error handling and exceptions
Test edge cases and boundary conditions
Test validation logic
Mock external dependencies (database, APIs)
Verify async/await behavior

Run

pytest --cov=backend --cov-report=term-missing

Check coverage report for gaps
Aim for 80%+ coverage

Project Testing Structure

Your qwarty backend testing structure:

backend/
  tests/
    conftest.py              # Global fixtures
    unit/
      domain/
        artist/
          test_artist_repository.py
          test_artist_service.py
        artwork/
        auth/
        ...
      middleware/
        test_error_handler.py
      utils/
        test_utils.py
    integration/             # End-to-end tests
      test_artist_api.py
      test_auth_flow.py

Common Test Patterns Quick Reference

Basic Async Test

python

import pytest
from sqlmodel.ext.asyncio.session import AsyncSession

@pytest.mark.asyncio
async def test_get_artist_by_id(db_session: AsyncSession):
    # Arrange
    artist_id = "test-artist-id"

    # Act
    result = await repository.get_by_id(artist_id)

    # Assert
    assert result is not None
    assert result.id == artist_id

Mocking Database Session

python

from unittest.mock import AsyncMock, MagicMock

@pytest.mark.asyncio
async def test_create_artist_success():
    # Arrange
    mock_session = AsyncMock(spec=AsyncSession)
    mock_session.execute = AsyncMock()
    mock_session.commit = AsyncMock()

    # Act
    service = ArtistService(mock_session)
    result = await service.create_artist(data)

    # Assert
    assert mock_session.commit.called

Testing FastAPI Routes

python

from fastapi.testclient import TestClient
from backend.main import create_application

@pytest.fixture
def client():
    app = create_application()
    return TestClient(app)

def test_get_artist_endpoint(client):
    # Act
    response = client.get("/api/v1/artists/test-id")

    # Assert
    assert response.status_code == 200
    assert response.json()["id"] == "test-id"

Test Organization Principles

Test Structure (AAA Pattern)

Arrange: Set up test data, mocks, fixtures
Act: Execute the code under test
Assert: Verify the expected outcome

Test Naming Convention

python

# Pattern: test_<what>_<when>_<expected>
def test_create_artist_with_valid_data_returns_artist()
def test_get_artist_when_not_found_raises_not_found_error()
def test_update_artist_with_duplicate_name_raises_conflict_error()

Test Organization

Unit tests: Test individual functions/methods in isolation
Integration tests: Test multiple components working together
Group related tests: Use test classes for related functionality

Topic Guides

🏗️ Testing Architecture

Three-Layer Testing Strategy:

Repository Layer: Test database queries, CRUD operations
Service Layer: Test business logic, orchestration
Router Layer: Test API endpoints, request/response handling

Key Concepts:

Mock dependencies at layer boundaries
Test each layer independently
Use integration tests for end-to-end flows
Maintain test isolation

📖 Complete Guide: resources/testing-architecture.md

🧪 Unit Testing

Unit Test Best Practices:

Test single responsibility
Mock external dependencies
Fast execution (no database, no network)
Independent and isolated
Test both success and failure paths

Unit Test Pattern:

python

@pytest.mark.asyncio
async def test_artist_service_create():
    # Mock repository
    mock_repo = AsyncMock()
    mock_repo.create = AsyncMock(return_value=artist_model)

    # Test service logic
    service = ArtistService(mock_repo)
    result = await service.create_artist(data)

    assert result.name == data.name

📖 Complete Guide: resources/unit-testing.md

🔗 Integration Testing

Integration Test Focus:

Test multiple components together
Use real database (test database)
Verify end-to-end workflows
Test API contracts

Integration Test Pattern:

python

@pytest.mark.asyncio
async def test_create_artist_flow(db_session, client):
    # Full flow: API → Service → Repository → DB
    response = client.post("/api/v1/artists", json=artist_data)
    assert response.status_code == 201

    # Verify in database
    artist = await db_session.get(Artist, response.json()["id"])
    assert artist is not None

📖 Complete Guide: resources/integration-testing.md

⚡ Async Testing

Async Test Patterns:

Use
```
@pytest.mark.asyncio
```
decorator
Configure pytest-asyncio in conftest.py
Mock async functions with AsyncMock
Test async context managers
Handle async exceptions

Async Mock Pattern:

python

from unittest.mock import AsyncMock

@pytest.mark.asyncio
async def test_async_function():
    mock_func = AsyncMock(return_value="result")
    result = await mock_func()
    assert result == "result"
    mock_func.assert_awaited_once()

📖 Complete Guide: resources/async-testing.md

🎭 Mocking & Fixtures

Mocking Strategy:

Mock external dependencies (database, APIs, S3)
Use pytest fixtures for reusable test data
Mock at layer boundaries
Use MagicMock for sync, AsyncMock for async

Fixture Pattern:

python

import pytest

@pytest.fixture
def sample_artist():
    return Artist(
        id="test-id",
        name="Test Artist",
        bio="Test bio"
    )

@pytest.fixture
async def db_session():
    # Setup test database session
    async with get_test_session() as session:
        yield session
        await session.rollback()

📖 Complete Guide: resources/mocking-fixtures.md

📊 Coverage Best Practices

Coverage Strategy:

Aim for 80%+ coverage (project requirement)
Focus on critical business logic
Test error paths and edge cases
Use coverage reports to find gaps
Exclude non-testable code (config, main.py)

Coverage Commands:

bash

# Run tests with coverage
pytest --cov=backend --cov-report=term-missing

# Generate HTML report
pytest --cov=backend --cov-report=html

# Check coverage threshold
pytest --cov=backend --cov-fail-under=80

📖 Complete Guide: resources/coverage-best-practices.md

🚀 FastAPI Testing

FastAPI Test Patterns:

Use TestClient for route testing
Test request validation
Test response serialization
Test authentication/authorization
Test error handling middleware

TestClient Pattern:

python

from fastapi.testclient import TestClient

def test_create_artist_endpoint(client: TestClient):
    response = client.post(
        "/api/v1/artists",
        json={"name": "Artist", "bio": "Bio"}
    )
    assert response.status_code == 201
    data = response.json()
    assert data["name"] == "Artist"

📖 Complete Guide: resources/fastapi-testing.md

Navigation Guide

Need to...	Read this resource
Understand test structure	testing-architecture.md
Write unit tests	unit-testing.md
Write integration tests	integration-testing.md
Test async code	async-testing.md
Use mocks and fixtures	mocking-fixtures.md
Improve coverage	coverage-best-practices.md
Test FastAPI routes	fastapi-testing.md

Core Principles

Test Isolation: Each test runs independently, no shared state
AAA Pattern: Arrange, Act, Assert for clear test structure
Async Testing: Use pytest-asyncio for async code
Mock Dependencies: Mock external systems (database, APIs)
Layered Testing: Test each layer (repository, service, router) separately
Coverage Goals: Aim for 80%+ coverage, focus on business logic
Descriptive Names: Clear test names explain what, when, expected
Error Testing: Test both success and failure paths
Fast Tests: Unit tests should be fast (no real database)
Fixtures: Use fixtures for reusable test data and setup

Quick Reference: Test Template

python

"""Tests for Artist domain."""
import pytest
from unittest.mock import AsyncMock, MagicMock
from sqlmodel.ext.asyncio.session import AsyncSession

from backend.domain.artist.service import ArtistService
from backend.domain.artist.repository import ArtistRepository
from backend.domain.artist.model import Artist
from backend.dtos.artist import ArtistRequestDto
from backend.error import NotFoundError


@pytest.fixture
def sample_artist():
    """Fixture for sample artist data."""
    return Artist(
        id="test-artist-id",
        name="Test Artist",
        bio="Test bio"
    )


@pytest.fixture
def mock_session():
    """Fixture for mocked database session."""
    return AsyncMock(spec=AsyncSession)


class TestArtistRepository:
    """Test suite for ArtistRepository."""

    @pytest.mark.asyncio
    async def test_get_by_id_success(self, mock_session, sample_artist):
        """Test get_by_id returns artist when found."""
        # Arrange
        mock_result = MagicMock()
        mock_result.scalar_one_or_none.return_value = sample_artist
        mock_session.execute = AsyncMock(return_value=mock_result)

        repository = ArtistRepository(mock_session)

        # Act
        result = await repository.get_by_id("test-artist-id")

        # Assert
        assert result is not None
        assert result.id == sample_artist.id
        assert result.name == sample_artist.name

    @pytest.mark.asyncio
    async def test_get_by_id_not_found(self, mock_session):
        """Test get_by_id returns None when not found."""
        # Arrange
        mock_result = MagicMock()
        mock_result.scalar_one_or_none.return_value = None
        mock_session.execute = AsyncMock(return_value=mock_result)

        repository = ArtistRepository(mock_session)

        # Act
        result = await repository.get_by_id("nonexistent-id")

        # Assert
        assert result is None


class TestArtistService:
    """Test suite for ArtistService."""

    @pytest.mark.asyncio
    async def test_create_artist_success(self, mock_session, sample_artist):
        """Test create_artist creates and returns artist."""
        # Arrange
        mock_repo = AsyncMock()
        mock_repo.create = AsyncMock(return_value=sample_artist)

        service = ArtistService(mock_session)
        service._repository = mock_repo

        request_dto = ArtistRequestDto(
            name="Test Artist",
            bio="Test bio"
        )

        # Act
        result = await service.create_artist(request_dto)

        # Assert
        assert result.name == request_dto.name
        mock_repo.create.assert_awaited_once()

Current Project Configuration

Your qwarty backend test setup:

pytest.ini (in pyproject.toml):

toml

[tool.pytest.ini_options]
testpaths = ["tests"]
filterwarnings = ["ignore::DeprecationWarning"]
markers = [
    "security: marks tests as security tests (SQL injection, etc.)",
    "performance: marks tests as performance benchmarks",
]
addopts = [
    "--cov=backend",
    "--cov-report=term-missing",
    "--cov-report=html",
    "--cov-fail-under=80",
]

Test Dependencies:

pytest 8.4.2+
pytest-asyncio 0.24.0+
pytest-cov 6.0.0+

Coverage Exclusions:

Tests themselves (
```
tests/*
```
)
```
__init__.py
```
files
Main application entry (
```
backend/main.py
```
)
Some routers and specific domains (see pyproject.toml)

Related Skills

fastapi-backend-guidelines: Backend development patterns (what you're testing)
error-tracking: Error handling patterns to test

Skill Status: Modular structure with progressive loading for optimal context management

pytest-backend-testing

NPX Install

Tags

SKILL.md Content

Pytest Backend Testing Guidelines

Purpose

When to Use This Skill

Quick Start

New Test File Checklist

Test Coverage Checklist

Project Testing Structure

Common Test Patterns Quick Reference

Basic Async Test

Mocking Database Session

Testing FastAPI Routes

Test Organization Principles

Test Structure (AAA Pattern)

Test Naming Convention

Test Organization

Topic Guides

🏗️ Testing Architecture

🧪 Unit Testing

🔗 Integration Testing

⚡ Async Testing

🎭 Mocking & Fixtures

📊 Coverage Best Practices

🚀 FastAPI Testing

Navigation Guide

Core Principles

Quick Reference: Test Template

Current Project Configuration

Related Skills