setup.cfg configuration in PyTest

Introduction

The setup.cfg file helps you set options for pytest in one place. It makes running tests easier and consistent.

You want to set test options without typing them every time in the command line.

You want to ignore certain files or folders during testing.

You want to add markers to organize tests.

You want to change the default test discovery rules.

You want to configure plugins or test output formats.

Syntax

PyTest

[pytest]
addopts = <options>
markers =
    <marker1>: <description>
    <marker2>: <description>
python_files = <pattern>
python_classes = <pattern>
python_functions = <pattern>

# Example:
# [pytest]
# addopts = -v --maxfail=2
# markers =
#     slow: marks tests as slow
# python_files = test_*.py

The section header [pytest] tells pytest to read these settings.

Indent marker descriptions for clarity.

Examples

This example sets verbose output, stops after 1 failure, looks for files starting with test_, and defines two markers.

PyTest

[pytest]
addopts = -v --maxfail=1
python_files = test_*.py
markers =
    smoke: quick smoke tests
    regression: full regression tests

This example changes traceback style to short and sets class and function name patterns for test discovery.

PyTest

[pytest]
addopts = --tb=short
python_classes = Test*
python_functions = test_*

Sample Program

This setup.cfg file adds verbose output and defines a marker named example. The test file has two tests, one marked with example.

PyTest

# Directory structure:
# project/
# ├── setup.cfg
# └── test_sample.py

# Content of setup.cfg:
# [pytest]
# addopts = -v
# markers =
#     example: marks example tests

# Content of test_sample.py:
import pytest

@pytest.mark.example
def test_addition():
    assert 1 + 1 == 2

def test_subtraction():
    assert 5 - 3 == 2

Important Notes

Use pytest --markers to see all markers available.

Keep setup.cfg in your project root for pytest to find it automatically.

Indentation and spacing matter in setup.cfg for readability but not strict syntax.

Summary

setup.cfg stores pytest settings in one file.

It helps run tests with consistent options without typing commands each time.

You can define markers, test file patterns, and other options easily.