How to Use conftest.py in pytest for Shared Fixtures and Hooks

In pytest, conftest.py is a special file used to define fixtures and hooks that can be shared across multiple test files without importing them explicitly. Place conftest.py in your test directory, and pytest will automatically discover and apply its contents to your tests.

Syntax

The conftest.py file contains fixture functions and hook implementations. Fixtures are defined using the @pytest.fixture decorator. Hooks are special functions pytest calls at certain points during test execution.

Example parts:

• @pytest.fixture: marks a function as a fixture.
• Fixture function: returns data or setup needed by tests.
• Hook function: named according to pytest hook specifications, e.g., pytest_runtest_setup.

python

import pytest

@pytest.fixture
def sample_fixture():
    return "data"

# Hook example
def pytest_runtest_setup(item):
    print(f"Setting up {item.name}")

Example

This example shows how conftest.py provides a fixture to test files automatically. The test uses the fixture without importing it.

python

# conftest.py
import pytest

@pytest.fixture
def greeting():
    return "Hello, pytest!"

# test_sample.py

def test_greeting(greeting):
    assert greeting == "Hello, pytest!"

Output

============================= test session starts =============================
collected 1 item

test_sample.py .                                                          [100%]

============================== 1 passed in 0.01s ==============================

Common Pitfalls

Common mistakes when using conftest.py include:

• Placing conftest.py outside the test directory so pytest cannot find it.
• Trying to import fixtures from conftest.py manually, which is unnecessary and can cause import errors.
• Defining fixtures with the same name in multiple conftest.py files in nested directories, causing confusion about which fixture is used.

python

## Wrong: importing fixture manually
# test_sample.py
#from conftest import greeting  # Avoid this

def test_greeting(greeting):
    assert greeting == "Hello, pytest!"


## Right: use fixture by name only
# test_sample.py

def test_greeting(greeting):
    assert greeting == "Hello, pytest!"

Quick Reference

Feature	Description	Usage
Fixture Definition	Create reusable setup code	@pytest.fixture def my_fixture(): ...
Automatic Discovery	pytest finds conftest.py automatically	Place conftest.py in test folder
No Imports Needed	Fixtures are available by name	Use fixture name as test argument
Hooks	Customize pytest behavior	def pytest_runtest_setup(item): ...
Scope Control	Control fixture lifetime	@pytest.fixture(scope='module')

Key Takeaways

Place conftest.py in your test directory to share fixtures and hooks automatically.

Define fixtures with @pytest.fixture to provide reusable test data or setup.

Do not import fixtures from conftest.py manually; pytest injects them by name.

Use hooks in conftest.py to customize pytest test execution behavior.

Be mindful of fixture scope and naming to avoid conflicts in nested test folders.