conftest

Pytest · Reference cheat sheet

📋 Overview

conftest.py holds shared fixtures, hooks, and plugins discovered by directory proximity. Nested conftests apply to their subtree; no import needed in tests.

🔧 Core concepts

Do not put conftest.py in importable app packages if it confuses packaging.

💡 Examples

Shared fixture:

# tests/conftest.py
import pytest

@pytest.fixture
def client(app):
    return app.test_client()

Hook — skip by mark in CI:

# tests/conftest.py
import os
import pytest

def pytest_collection_modifyitems(config, items):
    if os.getenv("CI"):
        return
    skip_ci = pytest.mark.skip(reason="CI only")
    for item in items:
        if "ci_only" in item.keywords:
            item.add_marker(skip_ci)

Nested override:

tests/
  conftest.py          # db fixture (sqlite)
  api/
    conftest.py        # db fixture (postgres) overrides for api/
    test_users.py

Register plugin:

pytest_plugins = ["tests.plugins.db"]

⚠️ Pitfalls

• Circular imports between conftest and application code.
• Putting secrets in conftest committed to git.
• Too many session fixtures in root conftest slowing collection.
• Expecting conftest fixtures across unrelated directories.
• Naming conflicts when two conftests define the same fixture name.

🔗 Related

• Fixtures
• Plugins
• Configuration
• Markers
• tmp_path
• Django pytest