setup.cfg configuration in PyTest - Deep Dive

Overview - setup.cfg configuration

What is it?

setup.cfg is a configuration file used to set options for Python projects, including pytest testing settings. It allows you to define how pytest runs tests without writing command-line arguments every time. This file uses a simple INI-style format to organize settings in sections. It helps keep your test setup consistent and easy to share.

Why it matters

Without setup.cfg, you would have to type long pytest commands or remember many options each time you run tests. This can lead to mistakes and inconsistent test runs. setup.cfg centralizes configuration, making tests easier to run, reproduce, and share with teammates. It saves time and reduces errors in testing workflows.

Where it fits

Before learning setup.cfg, you should understand basic pytest usage and command-line options. After mastering setup.cfg, you can explore more advanced pytest configuration files like pytest.ini or pyproject.toml, and learn about customizing test discovery and plugins.

Mental Model

Core Idea

setup.cfg is a simple text file that stores pytest settings so you don’t have to repeat them on the command line every time.

Think of it like...

It’s like setting your coffee machine to your favorite brew strength and cup size once, so every morning you just press start without adjusting settings again.

┌─────────────┐
│ setup.cfg   │
├─────────────┤
│ [tool:pytest]│
│ addopts=... │
│ testpaths=...│
│ markers=... │
└─────────────┘
      ↓
┌─────────────────────┐
│ pytest reads config  │
│ and applies options  │
└─────────────────────┘
      ↓
┌─────────────────────┐
│ Tests run with       │
│ consistent settings  │
└─────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is setup.cfg file

Concept: Introduce the setup.cfg file as a place to store project settings.

setup.cfg is a plain text file in your project folder. It uses sections marked by square brackets, like [tool:pytest], to group settings. You can put pytest options here instead of typing them in the terminal.

Result

You have a file ready to hold pytest settings, making your project organized.

Knowing that setup.cfg is just a text file helps you understand it’s easy to edit and share.

2

Foundation

Basic pytest options in setup.cfg

Concept: Learn how to add simple pytest options like test paths and extra arguments.

[tool:pytest] addopts = -v testpaths = tests This tells pytest to run tests in the 'tests' folder and show detailed output (-v).

Result

pytest will run tests from the specified folder with verbose output without extra command typing.

Setting common options here saves time and avoids forgetting important flags.

3

Intermediate

Using markers in setup.cfg

🤔Before reading on: do you think markers are just labels or do they affect test selection? Commit to your answer.

Concept: Markers are labels you assign to tests to group or select them during runs.

[tool:pytest] markers = slow: marks tests as slow smoke: quick checks You define markers here so pytest knows about them and won’t warn you.

Result

You can run tests by marker, like pytest -m slow, and avoid warnings about unknown markers.

Understanding markers lets you organize tests by categories and run subsets easily.

4

Intermediate

Configuring test discovery paths

🤔Before reading on: do you think pytest finds tests automatically everywhere or only in certain folders? Commit to your answer.

Concept: You can tell pytest exactly where to look for tests using testpaths in setup.cfg.

[tool:pytest] testpaths = tests integration This tells pytest to only look inside 'tests' and 'integration' folders for test files.

Result

pytest runs faster and avoids running unwanted scripts by limiting search to specified folders.

Controlling test discovery prevents accidental test runs and speeds up testing.

5

Advanced

Combining addopts with other settings

🤔Before reading on: do you think addopts can include multiple options or just one? Commit to your answer.

Concept: addopts can hold multiple command-line options as a single string in setup.cfg.

[tool:pytest] addopts = -v --maxfail=2 --tb=short This runs tests verbosely, stops after 2 failures, and shows short tracebacks.

Result

pytest runs with multiple behaviors controlled from one place, improving test feedback.

Knowing addopts can combine options helps you customize pytest runs fully in setup.cfg.

6

Expert

Overriding setup.cfg with CLI options

🤔Before reading on: do you think command-line options always override setup.cfg or the other way around? Commit to your answer.

Concept: Command-line options given when running pytest override settings in setup.cfg.

If setup.cfg has addopts = -v but you run pytest with -q (quiet), pytest uses -q instead of -v. This lets you have defaults but still customize runs easily.

Result

You get flexible test runs: defaults from setup.cfg but can change behavior anytime on the command line.

Understanding override rules prevents confusion when tests behave differently than expected.

Under the Hood

When you run pytest, it looks for configuration files in your project folder, including setup.cfg. It reads the [tool:pytest] section and parses options like addopts, testpaths, and markers. These options are merged with defaults and command-line arguments. Internally, pytest uses these settings to control test discovery, execution, and reporting.

Why designed this way?

setup.cfg was designed as a standard Python project configuration file to unify settings in one place. Using an INI-style format makes it easy to read and edit. It avoids scattering options across scripts or command lines, improving maintainability. Alternatives like pytest.ini exist, but setup.cfg fits well with other Python tools.

┌───────────────┐
│ User runs     │
│ 'pytest' cmd  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ pytest looks  │
│ for setup.cfg │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Reads [tool:pytest] │
│ section options │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Merges with   │
│ CLI args &    │
│ defaults      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Controls test │
│ discovery &   │
│ execution     │
└───────────────┘

Myth Busters - 3 Common Misconceptions

Quick: Does setup.cfg replace pytest.ini completely? Commit to yes or no before reading on.

Common Belief: setup.cfg replaces pytest.ini and you should only use one or the other.

Reality: Both setup.cfg and pytest.ini can configure pytest, but pytest.ini is pytest’s native config file. setup.cfg is a general Python config file that pytest also reads. You can use either, but pytest.ini is sometimes preferred for pytest-specific settings.

Why it matters: Choosing the wrong file can cause confusion or pytest ignoring some settings, leading to unexpected test behavior.

Quick: Do command-line options override setup.cfg settings or not? Commit to your answer.

Common Belief: Settings in setup.cfg always override command-line options.

Reality: Command-line options always override setup.cfg settings, allowing temporary changes without editing files.

Why it matters: Misunderstanding this leads to confusion when tests don’t run as expected after changing CLI options.

Quick: Can you put any pytest option in setup.cfg addopts? Commit to yes or no.

Common Belief: You can put any pytest command-line option inside addopts in setup.cfg.

Reality: Most options work, but some options that affect pytest’s startup or plugins may not behave as expected in addopts.

Why it matters: Using unsupported options in addopts can cause silent failures or ignored settings.

Expert Zone

1

Some pytest plugins add their own configuration sections in setup.cfg, so knowing how to merge plugin options is key for complex projects.

2

Whitespace and line continuation in setup.cfg addopts must be handled carefully to avoid parsing errors.

3

setup.cfg is read once at pytest startup; changing it during a test session has no effect until restart.

When NOT to use

For very complex pytest configurations or when you want to use TOML format, pyproject.toml is a better alternative. Also, if you want to isolate test settings per environment, using pytest.ini or environment variables might be preferable.

Production Patterns

In professional projects, setup.cfg is used to set default test paths, markers, and verbosity. Teams often combine it with CI/CD pipelines that override some options via command line for different test stages. Plugins like pytest-cov add coverage settings here, centralizing all test-related configs.

Connections

pyproject.toml configuration

Alternative configuration file format for pytest and other tools

Understanding setup.cfg helps grasp pyproject.toml because both centralize project settings but pyproject.toml uses TOML syntax and supports more tools.

Command-line interface (CLI) options

Overrides and complements setup.cfg settings

Knowing how CLI options override setup.cfg clarifies how to customize test runs temporarily without changing files.

Software configuration management

setup.cfg is an example of managing software behavior via config files

Recognizing setup.cfg as a config file connects to broader software practices of separating code from configuration for flexibility.

Common Pitfalls

#1 Forgetting to include [tool:pytest] section header

Wrong approach:

addopts = -v
testpaths = tests

Correct approach:

[tool:pytest]
addopts = -v
testpaths = tests

Root cause:

setup.cfg requires section headers to group settings; missing it means pytest ignores options.

#2 Putting invalid options in addopts causing pytest errors

Wrong approach:

[tool:pytest]
addopts = --unknown-option

Correct approach:

[tool:pytest]
addopts = -v

Root cause:

Not all command-line options are valid; unknown options cause pytest to fail or ignore settings.

#3 Using setup.cfg but expecting immediate effect after editing during a test session

Wrong approach:

Edit setup.cfg and rerun tests in same pytest session expecting changes

Correct approach:

Edit setup.cfg and restart pytest to apply changes

Root cause:

pytest reads setup.cfg only once at startup; changes need a restart to take effect.

Key Takeaways

setup.cfg is a simple text file that stores pytest settings to avoid repeating command-line options.

The [tool:pytest] section groups pytest-specific options like addopts, testpaths, and markers.

Command-line options always override setup.cfg settings, allowing flexible test runs.

Proper formatting and valid options in setup.cfg are essential to avoid pytest ignoring your settings.

setup.cfg fits into a larger Python project configuration ecosystem and helps maintain consistent, shareable test setups.