Examples

This section provides practical examples of using pytest-test-categories in various scenarios.

Topics

• Migration Guide
  • Overview
  • Phase 1: Installation and Initial Configuration
  • Phase 2: Categorizing Existing Tests
  • Phase 3: Fixing Common Violations
  • Phase 4: Enabling Strict Enforcement
  • Handling Edge Cases
  • Migration Checklist
  • Next Steps
  • Reference: Sample Project
• Common Testing Patterns
  • Mocking External Services for Small Tests
  • Fixture Patterns by Test Size
  • Test Organization Strategies
  • Parametrization Best Practices
  • Dependency Injection Patterns
  • Related Documentation
• CI Integration Guide
  • Core Principles
  • GitHub Actions
  • GitLab CI
  • Jenkins
  • Coverage Integration
  • Gradual Migration CI
  • Related Documentation
• Network Isolation Examples
  • Prerequisites
  • Example 1: HTTP API Client
  • Example 2: Database Integration
  • Example 3: Redis Cache
  • Example 4: External API with httpx
  • Example 5: Async HTTP Client
  • Configuration Examples
  • Related Documentation
• Filesystem Isolation Examples
  • Prerequisites
  • Example 1: Writing Report Files
  • Example 2: Reading Configuration Files
  • Example 3: File Processing Pipeline
  • Example 4: Log File Testing
  • Example 5: Database Fixture Files
  • Example 6: Using Medium Test Size
  • Configuration Examples
  • Related Documentation
• HTTP Mocking for Small Tests
  • Why Mock HTTP Requests?
  • pytest-httpx (for httpx)
  • responses (for requests)
  • httpretty (Library-Agnostic)
  • Choosing the Right Library
  • Testing Real API Clients
  • When Tests Need Real HTTP
  • Related Documentation
• Async Testing with pytest-asyncio
  • Why Async Testing Matters
  • Installation
  • Basic Configuration
  • Basic Async Tests
  • Async Fixtures
  • Timing Considerations
  • Async HTTP Mocking with respx
  • Mocking Async Functions
  • Testing Async Context Managers
  • Testing Async Iterators
  • Concurrent Test Execution
  • Best Practices
  • Related Documentation
• Database Testing Patterns
  • The Testing Pyramid for Databases
  • Small Tests: Repository Fakes
  • Small Tests: SQLite In-Memory
  • Medium Tests: pytest-postgresql
  • Medium Tests: Testcontainers
  • Fixture Patterns
  • Alembic Migration Testing
  • When to Use Each Approach
  • Best Practices
  • Related Documentation
• Container Testing with Testcontainers
  • Why Use Testcontainers?
  • Test Size Considerations
  • Installation
  • PostgreSQL Container
  • Redis Container
  • MySQL Container
  • MongoDB Container
  • Kafka Container
  • Elasticsearch Container
  • Fixture Scoping Strategies
  • When to Use Large vs Medium
  • Skipping When Docker Unavailable
  • Best Practices
  • Related Documentation
• IDE Configuration Examples
  • VS Code
  • PyCharm
  • Usage

Getting Started

If you are new to pytest-test-categories, start with these guides:

1. Migration Guide - Step-by-step process for adding pytest-test-categories to an existing project

2. Common Patterns - Fixture patterns, mocking strategies, and test organization

3. CI Integration - GitHub Actions, GitLab CI, and Jenkins examples

For isolation-specific examples, see:

• Network Isolation - Mocking HTTP, databases, and other network calls

• Filesystem Isolation - Using tmp_path and mocking file operations

Ecosystem Integration Guides

Guides for integrating pytest-test-categories with popular testing libraries:

• HTTP Mocking - pytest-httpx, responses, and httpretty for small tests

• Async Testing - pytest-asyncio integration and async mocking patterns

• Database Testing - SQLAlchemy, pytest-postgresql, and repository patterns

• Container Testing - Testcontainers for medium tests with real services

Quick Examples

Basic Test Marking

import pytest

@pytest.mark.small
def test_unit_logic():
    """Fast, hermetic unit test."""
    assert calculate_discount(100, 20) == 80

@pytest.mark.medium
def test_database_integration(db):
    """Integration test with local database."""
    user = UserRepository(db).create(name="Alice")
    assert user.id is not None

@pytest.mark.large
def test_end_to_end(staging_api):
    """End-to-end test with external services."""
    order = staging_api.create_order()
    assert order.status == "created"

Using Base Classes

from pytest_test_categories import SmallTest, MediumTest

class TestCalculator(SmallTest):
    def test_add(self):
        assert Calculator().add(1, 2) == 3

    def test_subtract(self):
        assert Calculator().subtract(5, 3) == 2

class TestUserRepository(MediumTest):
    def test_create_user(self, db):
        user = UserRepository(db).create(name="Alice")
        assert user.id is not None

Mocking for Small Tests

import pytest

@pytest.mark.small
def test_email_sender(mocker):
    """Mock external dependencies for small tests."""
    mock_smtp = mocker.patch("smtplib.SMTP")

    send_welcome_email("user@example.com")

    mock_smtp.return_value.send_message.assert_called_once()

Fixtures with Size Markers

import pytest

@pytest.fixture
def mock_api_client(mocker):
    """Fixture providing a mock API client for small tests."""
    client = mocker.Mock()
    client.get.return_value = {"status": "ok"}
    return client

@pytest.mark.small
def test_api_handler(mock_api_client):
    handler = APIHandler(client=mock_api_client)
    result = handler.fetch_status()
    assert result == "ok"