Pytest Testing Guide

Write Python tests efficiently with pytest.

Quick Start

pip install pytest

# test_example.py
def test_addition():
    assert 1 + 1 == 2

Run: pytest or pytest -v

Core Concepts

Concept	Example
Test function	def test_something():
Assertion	assert result == expected
Fixture	@pytest.fixture - dependency injection
Marker	@pytest.mark.skip - test metadata
Parametrize	@pytest.mark.parametrize - multiple inputs

Essential Patterns

Basic Test

def test_function():
    result = my_function(1, 2)
    assert result == 3

Exception Testing

import pytest

def test_raises():
    with pytest.raises(ValueError, match="invalid"):
        raise ValueError("invalid input")

Fixture (Setup/Teardown)

@pytest.fixture
def database():
    db = create_db()
    yield db          # provide to test
    db.cleanup()      # teardown

def test_query(database):
    assert database.query("SELECT 1")

Parametrize

@pytest.mark.parametrize("input,expected", [
    (1, 2),
    (2, 4),
    (3, 6),
])
def test_double(input, expected):
    assert input * 2 == expected

Mocking

def test_mock(monkeypatch):
    monkeypatch.setattr("module.func", lambda: "mocked")
    monkeypatch.setenv("API_KEY", "test-key")

Reference Files

Topic	File	When to Use
Basics	basics.md	Test discovery, assertions, running tests, config
Fixtures	fixtures.md	Setup/teardown, scopes, factories, conftest.py
Markers	markers.md	skip, xfail, parametrize, custom markers
Mocking	mocking.md	monkeypatch, pytest-mock, spies, async mocks
Plugins	plugins.md	Coverage, parallel, async, Django, Flask, FastAPI

Common Commands

pytest                    # Run all tests
pytest -v                 # Verbose
pytest -s                 # Show prints
pytest -x                 # Stop on first failure
pytest -k "pattern"       # Run matching tests
pytest -m slow            # Run by marker
pytest --cov=mypackage    # With coverage
pytest -n auto            # Parallel (xdist)
pytest --lf               # Run last failed
pytest --pdb              # Debug on failure

Project Structure

project/
├── src/
│   └── mypackage/
│       └── module.py
├── tests/
│   ├── conftest.py      # Shared fixtures
│   ├── test_unit.py
│   └── test_integration.py
├── pytest.ini           # Or pyproject.toml
└── requirements-test.txt

Configuration (pyproject.toml)

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"
markers = [
    "slow: slow tests",
    "integration: integration tests",
]

Built-in Fixtures

Fixture	Purpose
tmp_path	Temp directory (pathlib.Path)
tmpdir	Temp directory (legacy)
capsys	Capture stdout/stderr
caplog	Capture logging
monkeypatch	Patch attributes/env vars
request	Test/fixture metadata

Fixture Scopes

@pytest.fixture(scope="function")  # Default - per test
@pytest.fixture(scope="class")     # Per test class
@pytest.fixture(scope="module")    # Per file
@pytest.fixture(scope="session")   # Per test run

Best Practices

• Name tests descriptively: test_user_login_with_invalid_password_fails
• One assertion concept per test
• Use fixtures for reusable setup
• Use conftest.py for shared fixtures
• Use markers to categorize tests (unit, integration, slow)
• Run with coverage: pytest --cov --cov-report=html
• Use parametrize to reduce duplicate tests