Pytest Workflow & Testing Standards
A disciplined guide to engineering robust, fast, deterministic test suites using pytest.
1. Test Architecture & Directory Structure
Organize tests mirroring the application package layout:
my_project/
├── src/
│ └── my_pkg/
│ ├── core.py
│ └── service.py
├── tests/
│ ├── conftest.py # Shared fixtures, hooks, and test configuration
│ ├── unit/
│ │ ├── test_core.py
│ │ └── test_service.py
│ └── integration/
│ └── test_api.py
└── pyproject.toml
2. Fixture Design Principles
- Explicit Scoping: Prefer
functionscope for test isolation. Usemoduleorsessionstrictly for expensive read-only resources (e.g. database client pools or test containers). - Yield Fixtures for Cleanup: Always clean up resources using
yield. - Avoid Fixture Duplication: Place universal fixtures in
tests/conftest.py.
import pytest
from pathlib import Path
import tempfile
import shutil
@pytest.fixture
def temp_workspace():
"""Provide a clean temporary directory, cleaned up after test run."""
tmp = tempfile.mkdtemp(prefix="test-workspace-")
yield Path(tmp)
shutil.rmtree(tmp, ignore_errors=True)
3. Parametrization Patterns
Use @pytest.mark.parametrize to test boundary conditions, schemas, and edge cases:
@pytest.mark.parametrize("input_val, expected", [
("hello", "HELLO"),
("", ""),
("123", "123"),
])
def test_uppercase_conversion(input_val: str, expected: str):
assert input_val.upper() == expected
4. Mocking & Monkeypatching
- Use
monkeypatchfor standard environment variable and attribute substitution. - Use
unittest.mock.patchfor mocking external network calls or subprocesses. - Never mock the code under test—only its external boundaries.
5. Execution Flags & Verification
# Run unit tests with verbosity and fail-fast
pytest tests/unit -v -x
# Run with coverage report
pytest --cov=src/my_pkg --cov-report=term-missing tests/