pytest Setup

pytest discovers and runs tests by convention - no boilerplate test classes required. A tests/ directory, a pyproject.toml config block, and uv add --group dev pytest is enough to start.

Recipe

uv add --group dev pytest
mkdir tests

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

uv run pytest

When to reach for this:

• Starting tests on a new Python project
• Migrating from unittest to pytest
• Configuring test discovery for src/ layout

Working Example

myapp/
├── pyproject.toml
├── src/myapp/core.py
└── tests/
    ├── conftest.py
    └── test_core.py

# tests/test_core.py
from myapp.core import add
 
def test_add():
    assert add(2, 3) == 5

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = "-ra -q"
filterwarnings = ["error"]

uv run pytest -v
uv run pytest tests/test_core.py::test_add

What this demonstrates:

• Tests live in tests/, named test_*.py
• pythonpath = ["src"] enables imports without editable install in simple setups
• conftest.py holds shared fixtures
• addopts sets default CLI flags for every run

Deep Dive

Discovery Rules

• Files: test_*.py or *_test.py
• Functions: test_*
• Classes: Test* (no __init__)
• Plugins extend discovery (e.g., pytest-asyncio for async tests)

Config Locations

Gotchas

• Tests in project root - collected accidentally. Fix: testpaths = ["tests"] limits discovery.
• Import errors without src on path - ModuleNotFoundError. Fix: pythonpath = ["src"] or pip install -e ..
• Running pytest without dev deps - pytest: command not found. Fix: uv sync --group dev or uv run pytest.
• Duplicate conftest.py fixtures - name collisions across directories. Fix: scope fixtures carefully; use unique names.
• Warnings as noise - real issues hidden. Fix: filterwarnings = ["error"] to fail on unexpected warnings.

Alternatives

FAQs

Related

• Assertions & Test Structure - writing good tests
• Fixtures - setup and teardown
• Coverage & Reporting - measuring test reach
• Testing Best Practices - team conventions

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.