Mastering pytest.ini: Centralized Configuration for Efficient Python Testing

The pytest.ini file is the primary configuration file for pytest, automatically discovered in the current directory and its ancestors when the pytest command runs.

Why Use pytest.ini?

Centralized management : Keep all pytest settings in one place for easy maintenance.

Avoid verbose command lines : Move frequently used options into the file.

Project‑level consistency : Ensure every developer runs tests with the same configuration.

Suppress warnings : Register custom markers to prevent "unknown marker" warnings.

Environment variable handling : Define variables for the test session without hard‑coding them in code.

Boost test efficiency : A well‑tuned pytest.ini streamlines the test workflow.

Basic Structure

The file follows the INI format, with the main section named [pytest]:

[pytest]
testpaths = .
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = -v -ra -q
markers =
    slow: mark slow tests
    serial: mark tests that must run serially
    env: mark tests needing specific env vars
    flaky: mark unstable tests
    critical: mark critical tests
    performance: mark performance tests

Common Configuration Options

1. testpaths

Specifies directories where pytest looks for test files. Multiple paths can be listed.

[pytest]
testpaths = tests src  # search in both directories

2. python_files

Defines filename patterns for test discovery. Defaults are test_*.py and *_test.py.

[pytest]
python_files = test_*.py check_*.py *_tests.py

3. python_classes

Sets the naming pattern for test classes, defaulting to names that start with Test.

[pytest]
python_classes = Test Check Suite

4. python_functions

Sets the naming pattern for test functions, defaulting to the test_ prefix.

[pytest]
python_functions = test_* check_* example_*

5. markers

Registers custom markers to avoid warnings about unknown markers.

[pytest]
markers =
    slow: mark slow tests
    serial: mark tests that must run serially

6. addopts

Provides default command‑line options applied on every run.

[pytest]
addopts = -v -s --strict-markers --cov=my_package --cov-report=term-missing
# -v: verbose output
# -s: show print statements
# --strict-markers: error on unregistered markers
# --cov: enable coverage measurement
# --cov-report: format of coverage report

7. filterwarnings

Controls how Python warnings are displayed.

[pytest]
filterwarnings =
    ignore::DeprecationWarning  # ignore all deprecation warnings
    error::UserWarning          # treat user warnings as errors

8. norecursedirs

Excludes directories from test discovery, such as version‑control or virtual‑environment folders.

[pytest]
norecursedirs = .git _build tmp* venv*

9. minversion

Specifies the minimum pytest version required.

[pytest]
minversion = 6.0

10. env (requires pytest-env plugin)

Sets environment variables for the test session.

[pytest]
env =
    API_KEY=your_test_api_key
    D:DATABASE_URL=sqlite:///:memory:

Best Practices

Keep it simple : Include only necessary options.

Version control : Add pytest.ini to Git so the whole team shares the same settings.

Consult the official docs : pytest offers many more options; refer to the documentation for a complete list.

By thoughtfully configuring pytest.ini, teams can achieve more consistent, faster, and less error‑prone test runs.

pytest -v -s --strict-markers --cov=my_package --cov-report=term-missing
================================= test session starts =================================
platform win32 -- Python 3.13.3, pytest-8.3.5, pluggy-1.5.0 -- C:\Users\heish\AppData\Local\Programs\Python\Python313\python.exe
cachedir: .pytest_cache
rootdir: C:\src\mcp\mcp-server-demo
configfile: pytest.ini
testpaths: .
plugins: anyio-4.9.0, cov-4.1.0
collected 2 items

test_server.py::test_add PASSED
test_server.py::test_get_supported_chains PASSED
... (coverage warnings omitted) ...
================================== 2 passed in 3.21s =================================