pytest Cheatsheet: Fixtures, Parametrize and Marks Reference

# Install pytest + commonly-paired plugins
pip install "pytest>=8" pytest-cov pytest-xdist pytest-mock pytest-asyncio pytest-randomly

# Project layout (any of these — pytest auto-discovers)
#   tests/test_*.py
#   tests/*_test.py
#   src//tests/...
#
# Recommended: src/ layout + tests/ at repo root + conftest.py for fixtures.

# Run it
pytest                                  # all tests
pytest tests/test_api.py::test_login    # one test
pytest -k "login and not slow"          # name filter
pytest -m "smoke"                       # marker filter
pytest -x --ff                          # stop on first fail, retry failed-first
pytest -n auto                          # parallel (pytest-xdist)
pytest --cov=src --cov-report=html      # coverage + HTML report
pytest --lf                             # last-failed
pytest -vv --tb=short                   # verbose + concise traceback
pytest --collect-only -q                # show what would run

# tests/conftest.py — fixtures auto-discovered for every test below this dir
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import Session

@pytest.fixture(scope="session")
def engine():
    e = create_engine("sqlite:///:memory:")
    yield e
    e.dispose()                                # teardown after the session

@pytest.fixture
def db(engine) -> Session:                     # function-scoped (default)
    with Session(engine) as s:                 # rolled back between tests
        yield s

@pytest.fixture(autouse=True)
def reset_clock(monkeypatch):                  # runs for every test in scope
    monkeypatch.setattr("time.time", lambda: 1_700_000_000.0)

# Parametrize a fixture — every dependent test runs once per value
@pytest.fixture(params=[1, 2, 3], ids=["a", "b", "c"])
def n(request):
    return request.param

# Indirect parametrize — let the fixture transform the value
@pytest.fixture
def user(request):
    return {"plan": request.param}

@pytest.mark.parametrize("user", ["free", "pro"], indirect=True)
def test_billing(user):
    assert user["plan"] in {"free", "pro"}

# pyproject.toml — the modern home for pytest config
[tool.pytest.ini_options]
minversion       = "8.0"
testpaths        = ["tests"]
addopts          = "-ra -q --strict-markers --strict-config"
python_files     = ["test_*.py", "*_test.py"]
python_classes   = ["Test*"]
python_functions = ["test_*"]
pythonpath       = ["src"]
filterwarnings   = [
    "error",                                  # warnings fail tests by default
    "ignore::DeprecationWarning:third_party",
]
markers = [
    "slow:    deselect with -m 'not slow'",
    "smoke:   minimal subset for PR checks",
    "integration: hits external services",
]

# Coverage (pytest-cov / coverage.py)
[tool.coverage.run]
branch = true
source = ["src"]
omit   = ["*/migrations/*", "tests/*"]

[tool.coverage.report]
show_missing = true
skip_covered = true
fail_under   = 85
exclude_lines = ["pragma: no cover", "raise NotImplementedError"]

# tests/test_users.py — parametrize, fixtures, raises, mocker, marker.
import pytest
from unittest.mock import ANY
from myapp.users import create_user, BillingError

@pytest.mark.smoke
@pytest.mark.parametrize("plan,fee", [
    ("free", 0),
    ("pro",  10),
    ("max",  50),
])
def test_create_user(db, plan, fee):
    u = create_user(db, "ana@x.com", plan=plan)
    assert u.id and u.fee == fee

def test_duplicate_email_rejected(db):
    create_user(db, "ana@x.com")
    with pytest.raises(ValueError, match="already exists"):
        create_user(db, "ana@x.com")

def test_billing_error_logs(db, mocker):           # pytest-mock fixture
    log = mocker.patch("myapp.users.log.error")
    mocker.patch("myapp.users.charge", side_effect=BillingError)

    with pytest.raises(BillingError):
        create_user(db, "ana@x.com", plan="pro")

    log.assert_called_once_with("billing failed", user_id=ANY)

@pytest.mark.skipif("os.getenv('CI') is None",
                    reason="needs live Stripe key")
@pytest.mark.integration
def test_stripe_round_trip():
    ...