python-testing-standards

name	python-testing-standards
description	Comprehensive Python testing best practices, pytest conventions, test structure patterns (AAA, Given-When-Then), fixture usage, mocking strategies, code coverage standards, and common anti-patterns. Essential reference for code reviews, test writing, and ensuring high-quality Python test suites with pytest, unittest.mock, and pytest-cov.
allowed-tools	Read, Write, Grep, Glob

Python Testing Standards

Purpose

This skill provides comprehensive testing standards and best practices for Python projects using pytest. It serves as a reference guide during code reviews to ensure test quality, maintainability, and adherence to Python testing conventions.

When to use this skill:

• Conducting code reviews of Python test files
• Writing new test suites
• Refactoring existing tests
• Evaluating test coverage and quality
• Teaching testing best practices to team members

Context

High-quality tests are essential for maintaining reliable Python applications. This skill documents industry-standard testing practices using pytest, the de facto testing framework for modern Python development. These standards emphasize:

• Clarity: Tests should be easy to read and understand
• Maintainability: Tests should be easy to update as code evolves
• Reliability: Tests should be deterministic and fast
• Coverage: Tests should cover behavior, not just lines of code
• Isolation: Tests should be independent and not affect each other

This skill is designed to be referenced by the uncle-duke-python agent during code reviews and by developers when writing tests.

Prerequisites

Required Knowledge:

• Python fundamentals
• Basic understanding of testing concepts
• Familiarity with pytest (or willingness to learn)

Required Tools:

• pytest (pip install pytest)
• pytest-cov for coverage (pip install pytest-cov)
• pytest-mock for mocking (pip install pytest-mock)
• unittest.mock (built into Python 3.3+)

Expected Project Structure:

project/
├── src/
│   └── mypackage/
│       ├── __init__.py
│       └── module.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   │   └── test_module.py
│   └── integration/
│       └── test_integration.py
├── pytest.ini
└── requirements-dev.txt

---

Instructions

Task 1: Verify pytest Conventions

1.1 Test File Naming

Rule: Test files MUST follow one of these patterns:

• test_*.py (preferred)
• *_test.py

Examples:

✅ Good:

# File: test_user_service.py
# File: test_authentication.py
# File: user_service_test.py  # acceptable but less common

❌ Bad:

# File: user_tests.py  # missing 'test_' prefix
# File: test-user-service.py  # hyphens instead of underscores
# File: TestUserService.py  # CamelCase instead of snake_case

Why: pytest discovers test files by these patterns. Non-standard names won't be automatically discovered.

1.2 Test Function Naming

Rule: Test functions MUST start with test_ and describe the scenario being tested.

Pattern: test_<what>_<when>_<expected_behavior>

✅ Good:

def test_user_login_with_valid_credentials_returns_token():
    """Test that valid credentials return an auth token."""
    pass

def test_user_login_with_invalid_password_raises_authentication_error():
    """Test that invalid password raises AuthenticationError."""
    pass

def test_calculate_total_with_empty_cart_returns_zero():
    """Test that empty cart returns zero total."""
    pass

❌ Bad:

def test_login():  # Too vague
    pass

def test_user_service():  # Doesn't describe what's being tested
    pass

def testLogin():  # Missing underscore, CamelCase
    pass

def test_1():  # Non-descriptive
    pass

Why: Descriptive test names serve as documentation. When a test fails, the name should immediately tell you what broke.

1.3 Test Class Naming

Rule: Test classes MUST start with Test (no _test suffix).

✅ Good:

class TestUserAuthentication:
    """Tests for user authentication functionality."""

    def test_login_with_valid_credentials_succeeds(self):
        pass

    def test_login_with_invalid_credentials_fails(self):
        pass

class TestShoppingCart:
    """Tests for shopping cart operations."""

    def test_add_item_increases_count(self):
        pass

❌ Bad:

class UserAuthenticationTests:  # Missing 'Test' prefix
    pass

class Test_UserAuth:  # Unnecessary underscore
    pass

class testUserAuth:  # Lowercase 'test'
    pass

Why: pytest discovers test classes by the Test prefix. Classes provide logical grouping of related tests.

When to use classes vs functions:

• Use classes when tests share setup/teardown logic or fixtures
• Use functions for simple, independent tests
• Don't use classes just for grouping without shared behavior

1.4 Test Organization and Structure

Directory Structure:

tests/
├── __init__.py              # Makes tests a package
├── conftest.py              # Shared fixtures and configuration
├── unit/                    # Unit tests (fast, isolated)
│   ├── __init__.py
│   ├── test_models.py
│   ├── test_services.py
│   └── test_utils.py
├── integration/             # Integration tests (slower, external deps)
│   ├── __init__.py
│   ├── test_database.py
│   └── test_api_endpoints.py
└── e2e/                     # End-to-end tests (slowest)
    ├── __init__.py
    └── test_user_workflows.py

File Organization:

Within a test file, organize tests logically:

"""Tests for user authentication service."""

import pytest
from myapp.auth import AuthenticationService

# Fixtures at the top
@pytest.fixture
def auth_service():
    """Fixture providing authentication service instance."""
    return AuthenticationService()

# Test classes grouped by functionality
class TestUserLogin:
    """Tests for user login functionality."""

    def test_login_with_valid_credentials_succeeds(self, auth_service):
        pass

    def test_login_with_invalid_password_fails(self, auth_service):
        pass

class TestUserLogout:
    """Tests for user logout functionality."""

    def test_logout_invalidates_session(self, auth_service):
        pass

# Standalone functions for simple tests
def test_password_hashing_is_deterministic():
    """Test that same password always produces same hash."""
    pass

Task 2: Apply Test Structure Patterns

2.1 Arrange-Act-Assert (AAA) Pattern

Rule: Structure all tests using the AAA pattern with clear separation.

Pattern:

1. Arrange: Set up test data and preconditions
2. Act: Execute the behavior being tested
3. Assert: Verify the expected outcome

✅ Good:

def test_calculate_total_with_discount_applies_correctly():
    """Test that discount is correctly applied to cart total."""
    # Arrange
    cart = ShoppingCart()
    cart.add_item(Item(name="Widget", price=100.00))
    cart.add_item(Item(name="Gadget", price=50.00))
    discount = Discount(percentage=10)

    # Act
    total = cart.calculate_total(discount=discount)

    # Assert
    assert total == 135.00  # (100 + 50) * 0.9

✅ Good (with comments):

def test_user_registration_creates_new_user():
    """Test that user registration creates a new user record."""
    # Arrange
    user_data = {
        "username": "testuser",
        "email": "[e-mail]",
        "password": "SecurePass123!"
    }
    user_service = UserService()

    # Act
    user = user_service.register(user_data)

    # Assert
    assert user.username == "testuser"
    assert user.email == "[e-mail]"
    assert user.id is not None
    assert user.password_hash != user_data["password"]  # Hashed

❌ Bad:

def test_user_operations():
    # Everything mixed together
    user_service = UserService()
    user = user_service.register({"username": "test", "email": "[e-mail]"})
    assert user.username == "test"
    user.update_email("[e-mail]")
    assert user.email == "[e-mail]"
    user_service.delete(user.id)
    assert user_service.get(user.id) is None

Why bad: Tests multiple behaviors, hard to debug when it fails, violates single responsibility.

2.2 Given-When-Then (BDD Pattern)

Alternative to AAA: Given-When-Then is equivalent but uses BDD terminology.

Pattern:

1. Given: Preconditions and setup (same as Arrange)
2. When: Action being tested (same as Act)
3. Then: Expected outcome (same as Assert)

✅ Good:

def test_withdraw_with_sufficient_balance_succeeds():
    """
    Given an account with a balance of $100
    When withdrawing $30
    Then the withdrawal succeeds and balance is $70
    """
    # Given
    account = Account(balance=100.00)

    # When
    result = account.withdraw(30.00)

    # Then
    assert result is True
    assert account.balance == 70.00

Usage: Use Given-When-Then for behavior-driven tests, especially in integration/e2e tests. Use AAA for unit tests. Be consistent within a project.

2.3 Test Isolation

Rule: Each test MUST be completely independent and not rely on execution order.

✅ Good:

@pytest.fixture
def clean_database():
    """Provide a clean database for each test."""
    db = Database()
    db.clear()
    yield db
    db.clear()  # Cleanup after test

def test_create_user_adds_to_database(clean_database):
    """Test user creation adds record to database."""
    user = User(username="test")
    clean_database.save(user)

    assert clean_database.count() == 1

def test_delete_user_removes_from_database(clean_database):
    """Test user deletion removes record from database."""
    user = User(username="test")
    clean_database.save(user)
    clean_database.delete(user.id)

    assert clean_database.count() == 0

❌ Bad:

# Tests depend on execution order
db = Database()

def test_1_create_user():
    """This test must run first."""
    user = User(username="test")
    db.save(user)
    assert db.count() == 1

def test_2_delete_user():
    """This test depends on test_1 running first."""
    # Assumes user from test_1 exists
    users = db.get_all()
    db.delete(users[0].id)
    assert db.count() == 0

Why bad: Tests are brittle, fail when run in isolation or different order, hard to debug.

2.4 Test Data Management

Rule: Use fixtures, factories, or builders for test data. Avoid magic values.

✅ Good:

@pytest.fixture
def sample_user():
    """Provide a sample user for testing."""
    return User(
        username="john_doe",
        email="[e-mail]",
        age=30,
        is_active=True
    )

@pytest.fixture
def user_factory():
    """Provide a factory for creating test users."""
    def _create_user(**kwargs):
        defaults = {
            "username": "test_user",
            "email": "[e-mail]",
            "age": 25,
            "is_active": True
        }
        defaults.update(kwargs)
        return User(**defaults)
    return _create_user

def test_user_validation_with_invalid_age(user_factory):
    """Test that invalid age raises validation error."""
    user = user_factory(age=-5)

    with pytest.raises(ValidationError):
        user.validate()

❌ Bad:

def test_user_creation():
    # Magic values scattered throughout
    user = User("john", "[e-mail]", 30, True)
    assert user.username == "john"

def test_user_update():
    # Same magic values repeated
    user = User("john", "[e-mail]", 30, True)
    user.update_age(31)
    assert user.age == 31

Why bad: Hard to maintain, unclear what values mean, violates DRY principle.

Task 3: Implement Fixture Best Practices

3.1 Fixture Scopes

Rule: Choose the appropriate scope based on fixture cost and state.

Available Scopes:

• function: Default, runs before each test function (most common)
• class: Runs once per test class
• module: Runs once per module
• session: Runs once per test session

✅ Good:

@pytest.fixture(scope="session")
def database_engine():
    """Create database engine once per test session."""
    engine = create_engine("postgresql://localhost/test_db")
    yield engine
    engine.dispose()

@pytest.fixture(scope="module")
def database_schema(database_engine):
    """Create database schema once per module."""
    Base.metadata.create_all(database_engine)
    yield
    Base.metadata.drop_all(database_engine)

@pytest.fixture(scope="function")
def database_session(database_engine):
    """Provide a clean database session for each test."""
    connection = database_engine.connect()
    transaction = connection.begin()
    session = Session(bind=connection)

    yield session

    session.close()
    transaction.rollback()
    connection.close()

Scope Selection Guidelines:

• Use function scope for fixtures that need to be fresh for each test
• Use module or session scope for expensive setup (database connections, API clients)
• NEVER use broader scope for fixtures that maintain state between tests
• Always clean up in broader-scoped fixtures

❌ Bad:

@pytest.fixture(scope="session")
def user_list():
    """DON'T DO THIS - mutable state in session scope."""
    return []  # This list will be shared across ALL tests!

def test_add_user(user_list):
    user_list.append("user1")
    assert len(user_list) == 1  # Might fail if other tests run first

def test_remove_user(user_list):
    # Depends on state from other tests
    user_list.remove("user1")

Why bad: Shared mutable state causes tests to interfere with each other.

3.2 Fixture Dependencies

Rule: Fixtures can depend on other fixtures to build complex test scenarios.

✅ Good:

@pytest.fixture
def database():
    """Provide database connection."""
    db = Database("test.db")
    yield db
    db.close()

@pytest.fixture
def user(database):
    """Provide a test user in the database."""
    user = User(username="testuser")
    database.save(user)
    return user

@pytest.fixture
def authenticated_user(user):
    """Provide an authenticated user."""
    user.login()
    return user

def test_user_can_access_profile(authenticated_user, database):
    """Test authenticated user can access their profile."""
    profile = database.get_profile(authenticated_user.id)
    assert profile is not None
    assert profile.user_id == authenticated_user.id

Dependency Chain: database → user → authenticated_user

This approach builds complex test scenarios from simple, reusable fixtures.

3.3 Fixture Naming Conventions

Rule: Fixture names should be clear, descriptive nouns or noun phrases.

✅ Good:

@pytest.fixture
def database_session():
    """Provide a database session."""
    pass

@pytest.fixture
def mock_email_service():
    """Provide a mocked email service."""
    pass

@pytest.fixture
def sample_user_data():
    """Provide sample user data dictionary."""
    pass

@pytest.fixture
def http_client():
    """Provide an HTTP client for API testing."""
    pass

❌ Bad:

@pytest.fixture
def get_db():  # Verb, not noun
    pass

@pytest.fixture
def data():  # Too vague
    pass

@pytest.fixture
def fixture1():  # Non-descriptive
    pass

@pytest.fixture
def temp():  # Unclear what it provides
    pass

3.4 Fixtures vs Helper Functions

Rule: Use fixtures for setup/teardown and state. Use helper functions for operations.

✅ Good:

# Fixture for state/setup
@pytest.fixture
def user():
    """Provide a test user."""
    return User(username="test")

# Helper function for operations
def create_post(user, title, content):
    """Helper to create a post for testing."""
    return Post(author=user, title=title, content=content)

def test_user_can_create_post(user):
    """Test that user can create a post."""
    post = create_post(user, "Test Title", "Test Content")

    assert post.author == user
    assert post.title == "Test Title"

When to use fixtures:

• Setting up test data or objects
• Managing resources (database connections, file handles)
• Setup/teardown logic
• Sharing state across multiple tests

When to use helper functions:

• Performing operations in tests
• Reducing code duplication in test bodies
• Complex assertions
• Test data generation with many parameters

3.5 autouse Fixtures

Rule: Use autouse=True sparingly, only for fixtures that should always run.

✅ Good:

@pytest.fixture(autouse=True)
def reset_global_state():
    """Reset global application state before each test."""
    AppConfig.reset()
    Cache.clear()
    yield
    # Cleanup after test

@pytest.fixture(autouse=True, scope="session")
def configure_logging():
    """Configure logging for test session."""
    logging.basicConfig(level=logging.DEBUG)

❌ Bad:

@pytest.fixture(autouse=True)
def create_test_user():
    """DON'T DO THIS - not all tests need a user."""
    return User(username="test")  # Wastes resources for tests that don't need it

Use autouse when:

• Resetting global state
• Configuring logging/warnings
• Setting up test environment variables
• Cleanup that should always happen

Don't use autouse when:

• Only some tests need the fixture
• The fixture is expensive to create
• It makes test dependencies unclear

3.6 conftest.py Best Practices

Rule: Place shared fixtures in conftest.py at appropriate levels.

Directory Structure:

tests/
├── conftest.py              # Shared across ALL tests
├── unit/
│   ├── conftest.py          # Shared across unit tests only
│   └── test_services.py
└── integration/
    ├── conftest.py          # Shared across integration tests only
    └── test_database.py

Example conftest.py:

"""Shared fixtures for all tests."""

import pytest
from myapp import create_app
from myapp.database import Database

@pytest.fixture(scope="session")
def app():
    """Provide application instance for testing."""
    app = create_app(testing=True)
    return app

@pytest.fixture
def client(app):
    """Provide test client for making HTTP requests."""
    return app.test_client()

@pytest.fixture
def database():
    """Provide clean database for testing."""
    db = Database(":memory:")
    db.create_schema()
    yield db
    db.close()

# Register custom markers
def pytest_configure(config):
    """Register custom markers."""
    config.addinivalue_line(
        "markers", "slow: marks tests as slow (deselect with '-m \"not slow\"')"
    )
    config.addinivalue_line(
        "markers", "integration: marks tests as integration tests"
    )

Task 4: Apply Parametrization

Rule: Use @pytest.mark.parametrize to test multiple inputs without duplicating code.

✅ Good:

@pytest.mark.parametrize("value,expected", [
    (0, False),
    (1, True),
    (42, True),
    (-1, True),
    (-42, True),
])
def test_is_non_zero(value, expected):
    """Test is_non_zero function with various inputs."""
    assert is_non_zero(value) == expected

Multiple Parameters:

@pytest.mark.parametrize("username,email,valid", [
    ("john_doe", "[e-mail]", True),
    ("", "[e-mail]", False),  # Empty username
    ("john_doe", "", False),  # Empty email
    ("john_doe", "invalid-email", False),  # Invalid email format
    ("ab", "[e-mail]", False),  # Username too short
])
def test_user_validation(username, email, valid):
    """Test user validation with various inputs."""
    user = User(username=username, email=email)

    if valid:
        user.validate()  # Should not raise
    else:
        with pytest.raises(ValidationError):
            user.validate()

Using pytest.param for Test IDs:

@pytest.mark.parametrize("input_data,expected", [
    pytest.param(
        {"username": "john", "age": 30},
        User(username="john", age=30),
        id="valid_user"
    ),
    pytest.param(
        {"username": "", "age": 30},
        ValidationError,
        id="empty_username"
    ),
    pytest.param(
        {"username": "john", "age": -5},
        ValidationError,
        id="negative_age"
    ),
])
def test_user_creation(input_data, expected):
    """Test user creation with various inputs."""
    if isinstance(expected, type) and issubclass(expected, Exception):
        with pytest.raises(expected):
            User(**input_data)
    else:
        user = User(**input_data)
        assert user.username == expected.username
        assert user.age == expected.age

Parametrizing Fixtures:

@pytest.fixture(params=["sqlite", "postgresql", "mysql"])
def database(request):
    """Provide different database backends for testing."""
    db_type = request.param

    if db_type == "sqlite":
        db = SQLiteDatabase(":memory:")
    elif db_type == "postgresql":
        db = PostgreSQLDatabase("localhost", "test_db")
    elif db_type == "mysql":
        db = MySQLDatabase("localhost", "test_db")

    db.create_schema()
    yield db
    db.drop_schema()
    db.close()

def test_database_insert(database):
    """Test insert works on all database backends."""
    # This test runs 3 times, once for each database type
    database.insert("users", {"username": "test"})
    assert database.count("users") == 1

Task 5: Implement Mocking and Patching Best Practices

5.1 When to Mock vs When Not to Mock

Mock:

• External services (APIs, databases, email services)
• Slow operations (file I/O, network calls)
• Non-deterministic operations (random, datetime)
• Side effects you want to verify (logging, events)

Don't Mock:

• Simple data structures (dictionaries, lists)
• Pure functions with no side effects
• Your own internal business logic (test it directly)
• Value objects and entities

✅ Good (mocking external service):

def test_send_welcome_email_calls_email_service(mocker):
    """Test that user registration sends welcome email."""
    # Mock external email service
    mock_email = mocker.patch("myapp.services.EmailService.send")

    user_service = UserService()
    user = user_service.register("[e-mail]")

    # Verify email service was called
    mock_email.assert_called_once_with(
        to="[e-mail]",
        subject="Welcome!",
        template="welcome"
    )

❌ Bad (mocking internal logic):

def test_calculate_total(mocker):
    """DON'T DO THIS - mocking the thing you're testing."""
    cart = ShoppingCart()

    # Mocking internal method defeats the purpose of testing
    mocker.patch.object(cart, "calculate_total", return_value=100.0)

    assert cart.calculate_total() == 100.0  # Pointless test

5.2 unittest.mock Usage

Basic Mocking:

from unittest.mock import Mock, MagicMock, patch

def test_user_service_with_mock_database():
    """Test user service with mocked database."""
    # Create a mock database
    mock_db = Mock()
    mock_db.save.return_value = True
    mock_db.get.return_value = User(id=1, username="test")

    user_service = UserService(database=mock_db)
    user = user_service.create_user("test")

    # Verify interactions
    mock_db.save.assert_called_once()
    assert user.username == "test"

Using MagicMock for Magic Methods:

def test_context_manager():
    """Test code that uses context managers."""
    mock_file = MagicMock()
    mock_file.__enter__.return_value = mock_file
    mock_file.read.return_value = "test content"

    with mock_file as f:
        content = f.read()

    assert content == "test content"
    mock_file.__enter__.assert_called_once()
    mock_file.__exit__.assert_called_once()

5.3 pytest-mock Plugin

Preferred Approach: Use pytest-mock's mocker fixture for cleaner syntax.

✅ Good:

def test_get_user_data_from_api(mocker):
    """Test fetching user data from external API."""
    # Mock the requests.get call
    mock_get = mocker.patch("requests.get")
    mock_get.return_value.json.return_value = {
        "id": 1,
        "name": "John Doe"
    }
    mock_get.return_value.status_code = 200

    api_client = APIClient()
    user_data = api_client.get_user(user_id=1)

    # Verify API was called correctly
    mock_get.assert_called_once_with(
        "https://api.example.com/users/1",
        headers={"Authorization": "Bearer token"}
    )
    assert user_data["name"] == "John Doe"

Mocking Class Methods:

def test_service_calls_repository(mocker):
    """Test that service layer calls repository correctly."""
    # Mock the repository method
    mock_find = mocker.patch("myapp.repositories.UserRepository.find_by_email")
    mock_find.return_value = User(id=1, email="[e-mail]")

    service = UserService()
    user = service.get_user_by_email("[e-mail]")

    mock_find.assert_called_once_with("[e-mail]")
    assert user.email == "[e-mail]"

5.4 Patching Best Practices

Rule: Patch where the object is used, not where it's defined.

✅ Good:

# myapp/services.py
from myapp.repositories import UserRepository

class UserService:
    def get_user(self, user_id):
        return UserRepository.find(user_id)

# tests/test_services.py
def test_get_user(mocker):
    """Patch where UserRepository is USED."""
    # Correct: patch in myapp.services where it's imported
    mock_find = mocker.patch("myapp.services.UserRepository.find")
    mock_find.return_value = User(id=1)

    service = UserService()
    user = service.get_user(1)

    assert user.id == 1

❌ Bad:

def test_get_user(mocker):
    """DON'T DO THIS - patching where it's defined."""
    # Wrong: patch in myapp.repositories where it's defined
    mock_find = mocker.patch("myapp.repositories.UserRepository.find")
    # This won't work because UserService imported it before the patch

Patching Built-ins:

def test_file_processing(mocker):
    """Test file processing with mocked open."""
    mock_open = mocker.patch("builtins.open", mocker.mock_open(read_data="test data"))

    processor = FileProcessor()
    content = processor.read_file("test.txt")

    mock_open.assert_called_once_with("test.txt", "r")
    assert content == "test data"

Patching datetime:

from datetime import datetime

def test_timestamp_generation(mocker):
    """Test timestamp generation with frozen time."""
    # Mock datetime.now()
    mock_datetime = mocker.patch("myapp.utils.datetime")
    mock_datetime.now.return_value = datetime(2024, 1, 1, 12, 0, 0)

    timestamp = generate_timestamp()

    assert timestamp == "2024-01-01 12:00:00"

5.5 Mock Assertions

Rule: Always verify that mocks were called correctly.

Common Assertions:

def test_mock_assertions(mocker):
    """Demonstrate common mock assertions."""
    mock_service = mocker.Mock()

    # Call the mock
    mock_service.send_email("[e-mail]", "Hello")
    mock_service.send_email("[e-mail]", "World")

    # Verify it was called
    assert mock_service.send_email.called
    assert mock_service.send_email.call_count == 2

    # Verify specific calls
    mock_service.send_email.assert_called_with("[e-mail]", "World")
    mock_service.send_email.assert_any_call("[e-mail]", "Hello")

    # Verify all calls
    assert mock_service.send_email.call_args_list == [
        mocker.call("[e-mail]", "Hello"),
        mocker.call("[e-mail]", "World"),
    ]

Verify Mock Not Called:

def test_service_does_not_send_email_for_inactive_users(mocker):
    """Test that inactive users don't receive emails."""
    mock_email = mocker.patch("myapp.services.EmailService.send")

    user_service = UserService()
    user_service.notify_user(User(is_active=False))

    # Verify email was NOT sent
    mock_email.assert_not_called()

Side Effects:

def test_retry_logic_with_failures(mocker):
    """Test retry logic when API calls fail."""
    mock_api = mocker.Mock()
    # First two calls raise exception, third succeeds
    mock_api.fetch.side_effect = [
        ConnectionError("Failed"),
        ConnectionError("Failed"),
        {"status": "success"}
    ]

    client = APIClient(api=mock_api)
    result = client.fetch_with_retry(max_retries=3)

    assert result == {"status": "success"}
    assert mock_api.fetch.call_count == 3

Task 6: Implement Code Coverage Best Practices

6.1 Coverage Thresholds

Recommended Thresholds:

• Overall project: 80% minimum
• New code: 90% minimum (enforce in CI)
• Critical paths: 100% (authentication, payment, security)

pytest.ini Configuration:

[pytest]
# Run with coverage by default in CI
addopts = --cov=myapp --cov-report=html --cov-report=term --cov-fail-under=80

# Coverage options
[coverage:run]
omit =
    */tests/*
    */migrations/*
    */venv/*
    */__pycache__/*
    */site-packages/*

[coverage:report]
exclude_lines =
    pragma: no cover
    def __repr__
    raise AssertionError
    raise NotImplementedError
    if __name__ == .__main__.:
    if TYPE_CHECKING:
    @abstractmethod

Running Coverage:

# Generate coverage report
pytest --cov=myapp --cov-report=html --cov-report=term

# View HTML report
open htmlcov/index.html

# Fail if coverage below threshold
pytest --cov=myapp --cov-fail-under=80

# Show missing lines
pytest --cov=myapp --cov-report=term-missing

6.2 What to Test (and What Not to Test)

DO Test:

✅ Business Logic:

def calculate_discount(price, customer_tier):
    """Calculate discount based on customer tier."""
    if customer_tier == "gold":
        return price * 0.20
    elif customer_tier == "silver":
        return price * 0.10
    return 0.0

# TEST THIS - it's core business logic
def test_calculate_discount_for_gold_tier():
    assert calculate_discount(100.0, "gold") == 20.0

✅ Edge Cases and Boundaries:

def test_get_user_with_nonexistent_id_raises_error():
    """Test that fetching non-existent user raises NotFound."""
    with pytest.raises(NotFoundError):
        user_service.get_user(user_id=999999)

def test_divide_by_zero_raises_error():
    """Test division by zero raises appropriate error."""
    with pytest.raises(ZeroDivisionError):
        calculator.divide(10, 0)

✅ Error Handling:

def test_invalid_email_format_raises_validation_error():
    """Test that invalid email format raises ValidationError."""
    with pytest.raises(ValidationError, match="Invalid email format"):
        User(email="not-an-email")

✅ Public API/Interface:

class UserService:
    def register(self, email, password):  # Public API - TEST
        """Register a new user."""
        user = self._create_user(email)  # Private - don't test directly
        self._send_welcome_email(user)  # Private - don't test directly
        return user

# Test the public method, not private helpers
def test_register_creates_user_and_sends_email(mocker):
    mock_email = mocker.patch("myapp.services.EmailService.send")

    user = user_service.register("[e-mail]", "password")

    assert user.email == "[e-mail]"
    mock_email.assert_called_once()

DON'T Test:

❌ Framework/Library Code:

# DON'T test that Django's ORM works
def test_user_save():
    """DON'T DO THIS - testing Django, not your code."""
    user = User(username="test")
    user.save()
    assert User.objects.filter(username="test").exists()

❌ Trivial Getters/Setters:

class User:
    @property
    def username(self):
        return self._username  # DON'T test this

    @username.setter
    def username(self, value):
        self._username = value  # DON'T test this

❌ Private Implementation Details:

class Calculator:
    def add(self, a, b):
        return self._perform_addition(a, b)

    def _perform_addition(self, a, b):  # Private method
        return a + b

# DON'T test _perform_addition directly
# Test the public add() method instead

❌ Generated Code:

# DON'T test auto-generated migration files, __init__.py, etc.

6.3 Coverage Tools

pytest-cov:

# Install
pip install pytest-cov

# Basic usage
pytest --cov=myapp

# With HTML report
pytest --cov=myapp --cov-report=html

# Show missing lines
pytest --cov=myapp --cov-report=term-missing

# Multiple formats
pytest --cov=myapp --cov-report=html --cov-report=term --cov-report=xml

Coverage.py (underlying tool):

# Run tests with coverage
coverage run -m pytest

# Generate report
coverage report

# HTML report
coverage html

# Combine coverage from multiple runs
coverage combine
coverage report

Branch Coverage:

[coverage:run]
branch = True  # Enable branch coverage (not just line coverage)

def example(x):
    if x > 0:  # Branch 1
        return "positive"
    else:  # Branch 2
        return "non-positive"

# Line coverage: 100% if you test with x=1
# Branch coverage: 50% - you need to test both x>0 and x<=0

Task 7: Avoid Common Anti-Patterns

7.1 Anti-Pattern: Testing Implementation Details

❌ Bad:

def test_user_service_implementation_details():
    """DON'T DO THIS - testing how it works, not what it does."""
    service = UserService()

    # Testing that internal _validate method is called
    with patch.object(service, "_validate") as mock_validate:
        service.register("[e-mail]")
        mock_validate.assert_called_once()

✅ Good:

def test_user_service_validates_email():
    """Test the behavior: invalid emails are rejected."""
    service = UserService()

    # Test the behavior, not the implementation
    with pytest.raises(ValidationError):
        service.register("invalid-email")

Why: Implementation details change. Tests should verify behavior, not how the behavior is achieved.

7.2 Anti-Pattern: Overly Complex Test Setup

❌ Bad:

def test_complex_scenario():
    """DON'T DO THIS - setup is too complex."""
    # 50 lines of setup code
    db = Database()
    db.connect()
    db.create_tables()
    user1 = User(username="user1")
    user2 = User(username="user2")
    db.save(user1)
    db.save(user2)
    post1 = Post(author=user1, title="Post 1")
    post2 = Post(author=user2, title="Post 2")
    db.save(post1)
    db.save(post2)
    comment1 = Comment(post=post1, author=user2, text="Comment")
    db.save(comment1)
    # ... many more lines

    # Finally, the actual test
    result = service.get_posts()
    assert len(result) == 2

✅ Good:

@pytest.fixture
def database_with_posts():
    """Provide database with test posts."""
    db = Database()
    db.create_schema()

    users = [User(username=f"user{i}") for i in range(2)]
    posts = [Post(author=users[i], title=f"Post {i}") for i in range(2)]

    for user in users:
        db.save(user)
    for post in posts:
        db.save(post)

    yield db
    db.close()

def test_get_posts(database_with_posts):
    """Test retrieving posts."""
    result = service.get_posts()
    assert len(result) == 2

Why: Complex setup makes tests hard to read and maintain. Use fixtures and factories.

7.3 Anti-Pattern: Flaky Tests

❌ Bad:

import time
import random

def test_flaky_timing():
    """DON'T DO THIS - test depends on timing."""
    start = time.time()
    process_data()
    duration = time.time() - start

    # Flaky: might fail on slow systems
    assert duration < 1.0

def test_flaky_random():
    """DON'T DO THIS - test uses uncontrolled randomness."""
    result = generate_random_value()
    assert result > 5  # Might fail randomly

def test_flaky_order():
    """DON'T DO THIS - test depends on iteration order."""
    users = User.objects.all()  # Order not guaranteed
    assert users[0].username == "alice"

✅ Good:

def test_with_mocked_time(mocker):
    """Test with controlled time."""
    mock_time = mocker.patch("time.time")
    mock_time.side_effect = [0.0, 0.5]  # Controlled values

    start = time.time()
    process_data()
    duration = time.time() - start

    assert duration == 0.5

def test_with_seeded_random(mocker):
    """Test with controlled randomness."""
    mocker.patch("random.randint", return_value=7)

    result = generate_random_value()
    assert result == 7

def test_with_explicit_order():
    """Test with guaranteed order."""
    users = User.objects.all().order_by("username")
    assert users[0].username == "alice"

Why: Flaky tests erode trust in the test suite and waste developer time.

7.4 Anti-Pattern: Too Many Assertions in One Test

❌ Bad:

def test_user_operations():
    """DON'T DO THIS - testing multiple behaviors."""
    # Test 1: User creation
    user = User(username="test", email="[e-mail]")
    assert user.username == "test"
    assert user.email == "[e-mail]"

    # Test 2: User validation
    user.validate()
    assert user.is_valid is True

    # Test 3: User saving
    user.save()
    assert user.id is not None

    # Test 4: User updating
    user.username = "updated"
    user.save()
    assert user.username == "updated"

    # Test 5: User deletion
    user.delete()
    assert User.objects.filter(id=user.id).count() == 0

✅ Good:

def test_user_creation():
    """Test user is created with correct attributes."""
    user = User(username="test", email="[e-mail]")

    assert user.username == "test"
    assert user.email == "[e-mail]"

def test_user_validation_succeeds_for_valid_data():
    """Test validation succeeds for valid user data."""
    user = User(username="test", email="[e-mail]")

    user.validate()

    assert user.is_valid is True

def test_user_save_assigns_id():
    """Test saving user assigns an ID."""
    user = User(username="test", email="[e-mail]")

    user.save()

    assert user.id is not None

# ... separate tests for other behaviors

Guideline: One logical assertion per test. Multiple assert statements are okay if they verify the same behavior.

✅ Acceptable:

def test_user_creation_sets_all_attributes():
    """Test user creation sets all required attributes."""
    user = User(username="test", email="[e-mail]", age=30)

    # Multiple assertions, but all verify the same behavior (creation)
    assert user.username == "test"
    assert user.email == "[e-mail]"
    assert user.age == 30
    assert user.is_active is True  # Default value

7.5 Anti-Pattern: Not Testing Edge Cases

❌ Bad:

def test_divide():
    """Only tests the happy path."""
    assert divide(10, 2) == 5.0

✅ Good:

def test_divide_positive_numbers():
    """Test division of positive numbers."""
    assert divide(10, 2) == 5.0

def test_divide_negative_numbers():
    """Test division with negative numbers."""
    assert divide(-10, 2) == -5.0
    assert divide(10, -2) == -5.0

def test_divide_by_zero_raises_error():
    """Test division by zero raises ZeroDivisionError."""
    with pytest.raises(ZeroDivisionError):
        divide(10, 0)

def test_divide_zero_by_number():
    """Test zero divided by number returns zero."""
    assert divide(0, 5) == 0.0

def test_divide_floats():
    """Test division with floating point numbers."""
    assert divide(10.5, 2.0) == 5.25

Common Edge Cases to Test:

• Empty collections ([], {}, "")
• None values
• Zero
• Negative numbers
• Very large numbers
• Boundary values (max/min)
• Invalid input types
• Special characters in strings

7.6 Anti-Pattern: Missing Negative Test Cases

❌ Bad:

def test_create_user():
    """Only tests successful creation."""
    user = user_service.create("[e-mail]", "password123")
    assert user is not None

✅ Good:

def test_create_user_with_valid_data_succeeds():
    """Test user creation succeeds with valid data."""
    user = user_service.create("[e-mail]", "password123")
    assert user is not None

def test_create_user_with_invalid_email_raises_error():
    """Test user creation fails with invalid email."""
    with pytest.raises(ValidationError):
        user_service.create("invalid-email", "password123")

def test_create_user_with_short_password_raises_error():
    """Test user creation fails with short password."""
    with pytest.raises(ValidationError):
        user_service.create("[e-mail]", "pass")

def test_create_user_with_duplicate_email_raises_error():
    """Test user creation fails with duplicate email."""
    user_service.create("[e-mail]", "password123")

    with pytest.raises(DuplicateEmailError):
        user_service.create("[e-mail]", "password456")

Why: Negative tests verify error handling and validation logic.

---

Best Practices Summary

1. One Assertion Per Test (Guideline)

Guideline: Each test should verify one logical behavior. Multiple assert statements are acceptable if they all verify the same behavior.

✅ Good:

def test_user_registration_creates_complete_user():
    """Test user registration creates user with all attributes."""
    user = register_user("[e-mail]", "password")

    # All assertions verify the same behavior (successful registration)
    assert user.email == "[e-mail]"
    assert user.is_active is True
    assert user.created_at is not None

2. Test Names That Describe the Scenario

Pattern: test_<what>_<when>_<expected>

✅ Good:

def test_withdraw_with_insufficient_balance_raises_error():
    """Test withdrawing more than balance raises InsufficientFundsError."""
    pass

def test_login_with_valid_credentials_returns_token():
    """Test login with valid credentials returns auth token."""
    pass

3. Fast Tests

Rule: Unit tests should run in milliseconds, entire suite in seconds.

Strategies:

• Use in-memory databases (SQLite :memory:)
• Mock external dependencies
• Use fixtures with appropriate scopes
• Avoid unnecessary I/O operations
• Run slow tests separately (@pytest.mark.slow)

@pytest.mark.slow
def test_full_database_migration():
    """Slow test - run separately with pytest -m slow."""
    pass

# Run fast tests only
# pytest -m "not slow"

4. Independent Tests

Rule: Tests must not depend on each other or on execution order.

✅ Good:

@pytest.fixture(autouse=True)
def reset_database():
    """Reset database before each test."""
    db.clear()
    yield
    db.clear()

def test_create_user():
    """Each test starts with clean state."""
    user = create_user("test")
    assert db.count() == 1

def test_delete_user():
    """Independent of test_create_user."""
    user = create_user("test")
    delete_user(user.id)
    assert db.count() == 0

5. Repeatable Tests

Rule: Tests should produce the same results every time they run.

Avoid:

• Uncontrolled randomness
• System time dependencies
• External API calls
• Filesystem dependencies
• Network dependencies

Use:

• Mocked random with fixed seed
• Mocked datetime
• Mocked external services
• Temporary directories/files
• In-memory resources

6. Self-Validating Tests

Rule: Tests should clearly pass or fail without human interpretation.

✅ Good:

def test_calculate_total():
    """Test clearly passes or fails."""
    total = calculate_total([10, 20, 30])
    assert total == 60  # Clear pass/fail

❌ Bad:

def test_calculate_total():
    """Requires human to interpret output."""
    total = calculate_total([10, 20, 30])
    print(f"Total: {total}")  # No assertion - requires manual check

---

Examples

Example 1: Complete Test File

File: tests/unit/test_user_service.py

"""Tests for user service."""

import pytest
from myapp.models import User
from myapp.services import UserService
from myapp.exceptions import ValidationError, DuplicateEmailError


@pytest.fixture
def user_service():
    """Provide user service instance."""
    return UserService()


@pytest.fixture
def sample_user_data():
    """Provide sample valid user data."""
    return {
        "email": "[e-mail]",
        "password": "SecurePass123!",
        "username": "john_doe"
    }


class TestUserRegistration:
    """Tests for user registration functionality."""

    def test_register_with_valid_data_creates_user(self, user_service, sample_user_data):
        """Test that registration with valid data creates a user."""
        # Arrange
        # (data provided by fixture)

        # Act
        user = user_service.register(**sample_user_data)

        # Assert
        assert user.email == sample_user_data["email"]
        assert user.username == sample_user_data["username"]
        assert user.id is not None
         user.is_active  

     ():
        
        
        invalid_data = {
            : ,
            : ,
            : 
        }

        
         pytest.raises(ValidationError, =):
            user_service.register(**invalid_data)

     ():
        
        
        user_service.register(**sample_user_data)

        
         pytest.raises(DuplicateEmailError):
            user_service.register(**sample_user_data)


     ():
        
        
        user_data = {
            : ,
            : password,
            : 
        }

        
         should_fail:
             pytest.raises(ValidationError):
                user_service.register(**user_data)
        :
            user = user_service.register(**user_data)
             user   


 :
    


     ():
        
         user_service.register(**sample_user_data)

     ():
        
        
        email = sample_user_data[]
        password = sample_user_data[]

        
        token = user_service.login(email, password)

        
         token   
         (token, )
         (token) > 

     ():
        
        
        email = sample_user_data[]
        wrong_password = 

        
         pytest.raises(AuthenticationError):
            user_service.login(email, wrong_password)

     ():
        
        
        email = 
        password = 

        
         pytest.raises(AuthenticationError):
            user_service.login(email, password)


 :
    

     ():
        
        
        mock_email = mocker.patch()

        
        user = user_service.register(**sample_user_data)

        
        mock_email.assert_called_once_with(
            to=sample_user_data[],
            subject=,
            template=,
            context={: user.username}
        )

     ():
        
        
        mock_email = mocker.patch()
        invalid_data = {**sample_user_data, : }

        
         pytest.raises(ValidationError):
            user_service.register(**invalid_data)

        
        mock_email.assert_not_called()

Example 2: Testing with Fixtures and Factories

"""Example using fixtures and factories for test data."""

import pytest
from myapp.models import User, Post, Comment


@pytest.fixture
def user_factory(db):
    """Provide factory for creating test users."""
    created_users = []

    def _create_user(**kwargs):
        defaults = {
            "username": f"user_{len(created_users)}",
            "email": f"user{len(created_users)}@example.com",
            "is_active": True
        }
        defaults.update(kwargs)
        user = User(**defaults)
        db.save(user)
        created_users.append(user)
        return user

    yield _create_user

    # Cleanup
    for user in created_users:
        db.delete(user)


@pytest.fixture
def post_factory(db, user_factory):
    """Provide factory for creating test posts."""
    created_posts = []

    def _create_post(**kwargs):
        if "author" not in kwargs:
            kwargs["author"] = user_factory()

        defaults = {
            "title": f"Post {len(created_posts)}",
            "content": 
        }
        defaults.update(kwargs)
        post = Post(**defaults)
        db.save(post)
        created_posts.append(post)
         post

     _create_post

    
     post  created_posts:
        db.delete(post)


 ():
    
    
    user = user_factory(username=)

    
    post1 = post_factory(author=user, title=)
    post2 = post_factory(author=user, title=)

    
     post1.author == user
     post2.author == user
     user.posts.count() == 


 ():
    
    
    post = post_factory(title=)

    
     post.author   
     post.author.username.startswith()

Example 3: Integration Test with Database

"""Integration tests with real database."""

import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from myapp.models import Base, User
from myapp.repositories import UserRepository


@pytest.fixture(scope="module")
def engine():
    """Create in-memory SQLite engine for testing."""
    engine = create_engine("sqlite:///:memory:")
    Base.metadata.create_all(engine)
    yield engine
    Base.metadata.drop_all(engine)


@pytest.fixture
def db_session(engine):
    """Provide database session with transaction rollback."""
    connection = engine.connect()
    transaction = connection.begin()
    Session = sessionmaker(bind=connection)
    session = Session()

    yield session

    session.close()
    transaction.rollback()
    connection.close()


@pytest.fixture
def user_repository(db_session):
    """Provide user repository instance."""
    return UserRepository(session=db_session)


def test_create_user_persists_to_database(user_repository):
    """Test that created user is persisted to database."""
    # Arrange
    user_data = {
        "username": "testuser",
        "email": "[e-mail]"
    }

    # Act
    user = user_repository.create(**user_data)
    retrieved_user = user_repository.find_by_id(user.)

    
     retrieved_user   
     retrieved_user.username == 
     retrieved_user.email == 


 ():
    
    
    user1 = user_repository.create(username=, email=)
    user2 = user_repository.create(username=, email=)

    
    found_user = user_repository.find_by_email()

    
     found_user   
     found_user. == user2.
     found_user.username == 

---

Templates

Template 1: Basic Unit Test

Located at: templates/unit_test_template.py

Purpose: Template for basic unit tests using AAA pattern.

Usage:

1. Copy template to tests/unit/test_[module_name].py
2. Replace [MODULE_NAME] with actual module name
3. Replace [function/class] with code under test
4. Add test cases following the pattern

See: /Users/clo/developer/gh-clostaunau/holiday-card/.claude/skills/python-testing-standards/templates/unit_test_template.py

Template 2: Integration Test with Database

Located at: templates/integration_test_template.py

Purpose: Template for integration tests with database fixtures.

Usage:

1. Copy template to tests/integration/test_[feature_name].py
2. Configure database engine for your database
3. Add test cases using db_session fixture

See: /Users/clo/developer/gh-clostaunau/holiday-card/.claude/skills/python-testing-standards/templates/integration_test_template.py

Template 3: Test with Mocking

Located at: templates/mock_test_template.py

Purpose: Template for tests using mocks and patches.

Usage:

1. Copy template to appropriate test directory
2. Replace mock targets with actual dependencies
3. Add verification assertions

See: /Users/clo/developer/gh-clostaunau/holiday-card/.claude/skills/python-testing-standards/templates/mock_test_template.py

---

Decision Trees

When to Mock vs Test Real Implementation

Is the dependency external (API, database, file system)?
├─ Yes → Mock it
│   └─ Example: mock requests.get(), EmailService.send()
└─ No → Is it slow (>100ms)?
    ├─ Yes → Mock it
    │   └─ Example: mock expensive computations, large file processing
    └─ No → Is it non-deterministic (random, time)?
        ├─ Yes → Mock it
        │   └─ Example: mock datetime.now(), random.randint()
        └─ No → Is it your internal business logic?
            ├─ Yes → Test it directly (don't mock)
            │   └─ Example: test calculation functions, validators
            └─ No → Is it a framework/library?
                ├─ Yes → Don't test it (trust the framework)
                └─ No → Consider mocking if needed for isolation

Choosing Fixture Scope

Does the fixture need to be fresh for each test?
├─ Yes → Use scope="function" (default)
│   └─ Example: test data, mutable objects
└─ No → Is the fixture expensive to create?
    ├─ Yes → Is it stateless/read-only?
    │   ├─ Yes → Use scope="module" or "session"
    │   │   └─ Example: database connection, API client
    │   └─ No → Use scope="function" with cleanup
    │       └─ Example: database with data
    └─ No → Use scope="function" for simplicity

Test Organization Strategy

What are you testing?
├─ Single function/method with no dependencies
│   └─ Use standalone test function
│       └─ Example: def test_calculate_sum()
├─ Multiple related functions/methods
│   └─ Use test class for grouping
│       └─ Example: class TestUserAuthentication
├─ Tests sharing setup/teardown
│   └─ Use test class with fixtures
│       └─ Example: class TestDatabaseOperations with setup fixtures
└─ Different test types (unit/integration/e2e)
    └─ Use separate directories
        └─ Example: tests/unit/, tests/integration/, tests/e2e/

---

Common Pitfalls

Pitfall 1: Mocking Too Much

Problem: Over-mocking makes tests brittle and defeats the purpose of testing.

Why it happens: Desire for fast tests or lack of understanding of what to mock.

How to avoid:

• Only mock external dependencies and slow operations
• Test real implementation of your business logic
• Use integration tests for testing components together

Example:

❌ Bad:

def test_user_service_register(mocker):
    """Over-mocked test that doesn't test anything real."""
    mock_user = mocker.Mock()
    mock_validator = mocker.patch("myapp.validators.EmailValidator")
    mock_hasher = mocker.patch("myapp.security.hash_password")
    mock_repo = mocker.patch("myapp.repositories.UserRepository")

    # This test doesn't test any real code!
    service = UserService()
    service.register("[e-mail]", "password")

    mock_validator.validate.assert_called_once()
    mock_hasher.assert_called_once()
    mock_repo.save.assert_called_once()

✅ Good:

def test_user_service_register(mocker):
    """Test real logic, mock only external dependencies."""
    # Only mock external dependencies (database, email)
    mock_email = mocker.patch("myapp.services.EmailService.send")

    # Test real validation, hashing, and service logic
    service = UserService()
    user = service.register("[e-mail]", "SecurePass123!")

    # Verify real behavior
    assert user.email == "[e-mail]"
    assert user.password_hash != "SecurePass123!"  # Password was hashed
    mock_email.assert_called_once()  # Email was sent

Pitfall 2: Testing Private Methods

Problem: Tests are coupled to implementation details and break on refactoring.

Why it happens: Misconception that 100% coverage requires testing private methods.

How to avoid:

• Test public API/interface only
• Private methods are tested indirectly through public methods
• If a private method seems complex enough to test directly, it might deserve to be a separate class

Example:

❌ Bad:

class UserService:
    def register(self, email, password):
        self._validate_email(email)
        self._validate_password(password)
        return self._create_user(email, password)

    def _validate_email(self, email):
        # Private validation logic
        pass

    def _create_user(self, email, password):
        # Private creation logic
        pass

# DON'T DO THIS
def test_validate_email():
    """Testing private method directly."""
    service = UserService()
    service._validate_email("[e-mail]")  # Bad!

✅ Good:

# Test the public API
def test_register_with_invalid_email_raises_error():
    """Test registration validates email (tests _validate_email indirectly)."""
    service = UserService()

    with pytest.raises(ValidationError):
        service.register("invalid-email", "SecurePass123!")

def test_register_with_valid_data_creates_user():
    """Test registration creates user (tests _create_user indirectly)."""
    service = UserService()

    user = service.register("[e-mail]", "SecurePass123!")

    assert user.email == "[e-mail]"

Pitfall 3: Shared State Between Tests

Problem: Tests fail or pass depending on execution order.

Why it happens: Using module-level or class-level mutable state without proper cleanup.

How to avoid:

• Use fixtures with proper scope
• Clean up state in fixtures (use yield for teardown)
• Avoid module-level globals
• Use autouse=True fixtures for necessary cleanup

Example:

❌ Bad:

# Module-level shared state
_test_users = []

def test_create_user():
    """Test depends on _test_users being empty."""
    user = User(username="test")
    _test_users.append(user)
    assert len(_test_users) == 1  # Fails if other tests ran first!

def test_delete_user():
    """Test depends on test_create_user."""
    _test_users.pop()
    assert len(_test_users) == 0

✅ Good:

@pytest.fixture
def user_list():
    """Provide fresh list for each test."""
    users = []
    yield users
    users.clear()  # Cleanup (though not needed with function scope)

def test_create_user(user_list):
    """Test with isolated state."""
    user = User(username="test")
    user_list.append(user)
    assert len(user_list) == 1

def test_delete_user(user_list):
    """Test with isolated state."""
    user = User(username="test")
    user_list.append(user)
    user_list.pop()
    assert len(user_list) == 0

Pitfall 4: Not Cleaning Up Resources

Problem: Tests leave behind files, database records, or open connections.

Why it happens: Forgetting to add cleanup code or not using fixtures properly.

How to avoid:

• Use fixtures with yield for setup/teardown
• Use context managers
• Use temp directories for file tests
• Use transaction rollback for database tests

Example:

❌ Bad:

def test_file_processing():
    """Test leaves file behind."""
    with open("test_file.txt", "w") as f:
        f.write("test data")

    result = process_file("test_file.txt")
    assert result == "processed"
    # File left behind!

✅ Good:

import tempfile
import os

@pytest.fixture
def test_file():
    """Provide temporary test file."""
    fd, path = tempfile.mkstemp(suffix=".txt")

    # Write test data
    with os.fdopen(fd, "w") as f:
        f.write("test data")

    yield path

    # Cleanup
    if os.path.exists(path):
        os.remove(path)

def test_file_processing(test_file):
    """Test with automatic cleanup."""
    result = process_file(test_file)
    assert result == "processed"
    # File automatically cleaned up

Pitfall 5: Unclear Test Failure Messages

Problem: When test fails, it's not clear what went wrong.

Why it happens: Using bare assertions without context or descriptive messages.

How to avoid:

• Use descriptive test names
• Add assertion messages for complex checks
• Use pytest's assertion rewriting (automatic for simple assertions)
• Use pytest.raises() with match parameter

Example:

❌ Bad:

def test_user():
    """Vague test name."""
    u = User("[e-mail]")
    assert u.email == "[e-mail]"  # Failure message unclear

When this fails:

assert '[e-mail]' == '[e-mail]'

✅ Good:

def test_user_email_is_stored_correctly():
    """Descriptive test name explains what's being tested."""
    # Arrange
    email = "[e-mail]"

    # Act
    user = User(email)

    # Assert
    assert user.email == email, f"Expected user email to be {email}, got {user.email}"

When this fails:

AssertionError: Expected user email to be [e-mail], got [e-mail]

For Exceptions:

✅ Good:

def test_invalid_email_raises_validation_error():
    """Test that invalid email raises ValidationError with helpful message."""
    with pytest.raises(ValidationError, match="Invalid email format"):
        User("not-an-email")

---

Checklist

Use this checklist during code reviews to verify test quality:

Test File Organization

• Test files named test_*.py or *_test.py
• Tests organized in logical directories (unit/, integration/, e2e/)
• Shared fixtures in conftest.py at appropriate levels
• One test file per module/class being tested

Test Function/Class Naming

• Test functions start with test_
• Test classes start with Test
• Names describe the scenario: test_<what>_<when>_<expected>
• Names are clear and self-documenting

Test Structure

• Tests follow AAA or Given-When-Then pattern
• Clear separation between Arrange, Act, Assert
• Each test verifies one logical behavior
• Tests are independent and can run in any order

Fixtures

• Appropriate fixture scope selected (function/class/module/session)
• Fixtures have descriptive names
• Fixtures clean up resources (using yield)
• Fixture dependencies are logical and clear
• autouse only used when necessary

Mocking and Patching

• Only external dependencies are mocked
• Internal business logic is tested directly
• Patches target where object is used, not where it's defined
• Mock assertions verify expected behavior
• Mocks are reset between tests (automatic with mocker fixture)

Test Coverage

• Critical paths have 100% coverage
• Overall coverage meets project threshold (80%+)
• Coverage report excludes irrelevant files (migrations, etc.)
• Business logic is thoroughly tested
• Edge cases are covered

Assertions

• Tests have at least one assertion
• Assertions are specific and meaningful
• Exception tests use pytest.raises()
• Assertion messages provided for complex checks
• No bare assert without verification

Test Quality

• No testing of implementation details
• No overly complex test setup
• Tests are not flaky (deterministic)
• Edge cases are tested
• Negative test cases are included
• Tests are fast (unit tests < 100ms)

Parametrization

• @pytest.mark.parametrize used for multiple similar test cases
• Test IDs provided for clarity (using pytest.param)
• Parametrized tests cover full range of inputs

Code Quality

• Tests follow PEP 8 style guide
• Tests have docstrings describing what they test
• No code duplication (use fixtures/helpers)
• Imports are organized and minimal
• No commented-out code

Documentation

• README explains how to run tests
• Complex test scenarios are documented
• Custom markers are registered and documented
• Fixture purposes are clear from docstrings

---

Tools and Commands

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/unit/test_user_service.py

# Run specific test function
pytest tests/unit/test_user_service.py::test_register_with_valid_data

# Run specific test class
pytest tests/unit/test_user_service.py::TestUserRegistration

# Run tests matching pattern
pytest -k "registration"

# Run tests with specific marker
pytest -m "slow"

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

# Verbose output
pytest -v

# Show print statements
pytest -s

# Stop after first failure
pytest -x

# Run last failed tests only
pytest --lf

# Run failed tests first, then rest
pytest --ff

# Show slowest tests
pytest --durations=10

Coverage Commands

# Run with coverage
pytest --cov=myapp

# HTML report
pytest --cov=myapp --cov-report=html

# Terminal report with missing lines
pytest --cov=myapp --cov-report=term-missing

# XML report (for CI)
pytest --cov=myapp --cov-report=xml

# Fail if coverage below threshold
pytest --cov=myapp --cov-fail-under=80

# Multiple reports
pytest --cov=myapp --cov-report=html --cov-report=term --cov-report=xml

Pytest Configuration

pytest.ini:

[pytest]
# Test discovery patterns
python_files = test_*.py *_test.py
python_classes = Test*
python_functions = test_*

# Default options
addopts =
    -v
    --strict-markers
    --tb=short
    --cov=myapp
    --cov-report=term-missing
    --cov-fail-under=80

# Test paths
testpaths = tests

# Markers
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    integration: marks tests as integration tests
    unit: marks tests as unit tests
    e2e: marks tests as end-to-end tests

# Coverage options
[coverage:run]
source = myapp
omit =
    */tests/*
    */migrations/*
    */venv/*
    */__pycache__/*

[coverage:report]
exclude_lines =
    pragma: no cover
    def __repr__
    raise AssertionError
    raise NotImplementedError
    if __name__ == .__main__.:
    if TYPE_CHECKING:
    @abstractmethod

Useful Pytest Plugins

# Install common plugins
pip install pytest-cov          # Coverage integration
pip install pytest-mock         # Mocking integration
pip install pytest-xdist        # Parallel test execution
pip install pytest-django       # Django integration
pip install pytest-asyncio      # Async test support
pip install pytest-timeout      # Test timeouts
pip install pytest-benchmark    # Performance benchmarking

# Run tests in parallel
pytest -n auto  # Uses all CPU cores
pytest -n 4     # Uses 4 workers

# Set test timeout
pytest --timeout=10  # 10 seconds per test

---

Related Skills

• uncle-duke-python: Python code review agent that uses this skill as reference
• agent-skill-templates: Templates for creating new skills

---

References

Official Documentation

• pytest Documentation
• unittest.mock Documentation
• pytest-cov Documentation
• pytest-mock Documentation

Best Practices Guides

• Effective Python Testing with pytest (Book)
• Python Testing Best Practices
• AAA Pattern
• Given-When-Then

PEPs Referenced

• PEP 8 - Style Guide for Python Code
• PEP 20 - The Zen of Python
• PEP 484 - Type Hints

---

Version: 1.0 Last Updated: 2025-12-24 Maintainer: Development Team