Python Test Design Skill Skill

Python Test Design Skill

Guidance for designing pytest test suites with modern Python 3.11+ patterns.

When to Use This Skill

Use this skill for test design decisions:

Planning test suite architecture
Choosing testing strategies (unit, integration, e2e)
Designing fixture hierarchies
Determining coverage strategies
Planning property-based testing approach

For test implementation, use the python-engineering:python-pytest-architect agent instead.

Test Design Principles

Load and follow the standards in /python-engineering:standards-for-python-development when aligning test strategy with shared plugin testing norms. The strategies below supplement those standards; they do not replace them.

Test Pyramid

Structure test suites following the test pyramid:

        /\
       /  \     E2E (few, slow, high confidence)
      /----\
     /      \   Integration (moderate, medium speed)
    /--------\
   /          \ Unit (many, fast, focused)
  /------------\

Distribution targets:

Unit tests: 70-80% of test count
Integration tests: 15-25% of test count
E2E tests: 5-10% of test count

Test Naming Convention

Use behavioral naming that describes what is being tested:

# Pattern: test_{function}_{scenario}_{expected_result}

def test_validate_email_with_invalid_format_raises_validation_error():
    """Validate that malformed emails are rejected."""
    ...

def test_process_payment_when_insufficient_funds_returns_declined():
    """Payment processing declines when balance is insufficient."""
    ...

AAA Pattern (Arrange-Act-Assert)

Structure every test with clear sections:

def test_user_registration_creates_account():
    # Arrange
    user_data = {"email": "test@example.com", "name": "Test User"}
    repository = InMemoryUserRepository()
    service = UserService(repository)

    # Act
    result = service.register(user_data)

    # Assert
    assert result.success is True
    assert repository.count() == 1

Test Strategy Selection

When to Use Unit Tests

Pure functions with no side effects
Business logic validation
Data transformation
Algorithm correctness

When to Use Integration Tests

Database interactions
External API calls
File system operations
Multi-component workflows

When to Use Property-Based Tests

Functions with mathematical properties (commutativity, associativity)
Parsers and serializers (round-trip property)
Data validation (valid inputs always accepted)
State machines (invariants maintained)

from hypothesis import given, strategies as st

@given(st.lists(st.integers()))
def test_sort_maintains_length(data):
    """Sorting preserves all elements."""
    result = sorted(data)
    assert len(result) == len(data)

When to Use BDD Tests

User-facing features with acceptance criteria
Requirements traceability needed
Non-technical stakeholder visibility
Complex user workflows

Fixture Design

Fixture Hierarchy

Organize fixtures by scope and purpose:

conftest.py (root)
├── Session fixtures (db connections, servers)
├── Module fixtures (shared test data)
└── Function fixtures (isolated per-test data)

tests/
├── conftest.py              # Shared fixtures
├── unit/
│   └── conftest.py          # Unit-specific fixtures
└── integration/
    └── conftest.py          # Integration-specific fixtures

Factory Pattern for Test Data

Use factories for complex test objects:

import factory
from datetime import datetime, UTC

class UserFactory(factory.Factory):
    class Meta:
        model = User

    id = factory.Sequence(lambda n: n)
    email = factory.LazyAttribute(lambda o: f"user{o.id}@example.com")
    created_at = factory.LazyFunction(lambda: datetime.now(UTC))

Coverage Strategy

Minimum Coverage Requirements

| Code Type | Minimum Coverage | | ----------------- | ---------------------- | | Business logic | 90% | | Standard code | 80% | | Scripts/utilities | 70% | | Critical paths | 95% + mutation testing |

Coverage Configuration

# pyproject.toml
[tool.coverage.run]
branch = true
source = ["packages"]
omit = ["**/tests/**", "**/__pycache__/**"]

[tool.coverage.report]
fail_under = 80
exclude_lines = [
    "pragma: no cover",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
]

Mutation Testing for Critical Code

Apply mutation testing to security-critical and payment-related code:

# Run mutation tests on auth module
uv run mutmut run --paths-to-mutate=packages/auth/

# View surviving mutants
uv run mutmut results

Target: >90% mutation score for critical code paths

Test Directory Structure

tests/
├── conftest.py              # Shared fixtures, pytest plugins
├── unit/                    # Fast, isolated tests
│   ├── test_validators.py
│   └── test_models.py
├── integration/             # Tests with external dependencies
│   ├── test_database.py
│   └── test_api_client.py
├── e2e/                     # End-to-end workflows
│   └── test_user_flows.py
├── fixtures/                # Test data files
│   ├── sample_config.yaml
│   └── test_data.json
└── conftest.py              # Root-level configuration

Related Resources

Agent: Use python-engineering:python-pytest-architect for test implementation
Skill: python-engineering:python3-core for general Python patterns
Skill: python-engineering:python3-testing for test implementation patterns
Command: /python-engineering:modernpython for modern Python syntax reference

Agent Skills: Python Test Design Skill

Install this agent skill to your local

Skill Files