Addopts for default options in PyTest - Deep Dive

Overview - Addopts for default options

What is it?

Addopts is a way to set default command-line options for pytest, a popular testing tool in Python. Instead of typing the same options every time you run tests, you can save them in a configuration file. This makes running tests easier and more consistent. It helps automate common settings like verbosity or test selection.

Why it matters

Without addopts, testers must remember and type long commands repeatedly, which wastes time and risks mistakes. Default options ensure tests run the same way every time, improving reliability and saving effort. This consistency helps teams avoid confusion and speeds up finding problems in code.

Where it fits

Before learning addopts, you should know basic pytest usage and how to run tests from the command line. After mastering addopts, you can explore more advanced pytest configuration, plugins, and continuous integration setups.

Mental Model

Core Idea

Addopts lets you save your favorite pytest command options so you never have to type them again.

Think of it like...

It's like setting your coffee machine to your favorite brew strength and cup size so every morning you get the same perfect coffee without adjusting settings.

pytest.ini or tox.ini or setup.cfg
└── [pytest]
    └── addopts = --verbose --maxfail=2

When you run 'pytest', it automatically uses these options.

Build-Up - 6 Steps

1

Foundation

What is pytest addopts?

Concept: Addopts is a configuration setting to store default pytest command options.

Pytest runs tests with commands like 'pytest -v' for verbose output. Typing options every time is repetitive. Addopts lets you write these options once in a config file like pytest.ini under the [pytest] section. For example: [pytest] addopts = -v Now, running 'pytest' uses verbose mode by default.

Result

Pytest runs with the saved options automatically, saving typing and ensuring consistency.

Understanding addopts reduces repetitive typing and human error in running tests.

2

Foundation

Where to put addopts settings

Concept: Addopts can be placed in several config files pytest reads automatically.

Pytest looks for configuration in files like pytest.ini, tox.ini, or setup.cfg. You add addopts under the [pytest] section in any of these files at your project root. For example, in pytest.ini: [pytest] addopts = --maxfail=1 --tb=short This means pytest stops after one failure and shows short tracebacks.

Result

Pytest reads the config file and applies the options every time you run tests in that project.

Knowing where to place addopts lets you control test runs project-wide without extra commands.

3

Intermediate

Combining addopts with command line

🤔Before reading on: If you run 'pytest --maxfail=3' but addopts has '--maxfail=1', which maxfail value applies? Commit to your answer.

Concept: Command-line options override addopts defaults when both are used.

Addopts sets default options, but if you specify options directly on the command line, those take priority. For example, if addopts has '--maxfail=1' but you run 'pytest --maxfail=3', pytest will stop after 3 failures, not 1. This lets you override defaults temporarily.

Result

Command-line options always override addopts settings for flexibility.

Understanding this priority prevents confusion when tests behave differently than expected.

4

Intermediate

Using addopts for common test needs

🤔Before reading on: Would you put test selection options like '-k test_login' in addopts? Why or why not? Commit your reasoning.

Concept: Addopts is best for stable, common options, not for frequently changing test selectors.

Addopts is great for options like verbosity, maxfail, or capturing output. But options that change often, like selecting specific tests with '-k' or markers, are better passed on the command line. This keeps defaults useful and flexible.

Result

Tests run with consistent settings, while allowing easy overrides for specific runs.

Knowing when to use addopts vs command line keeps test runs efficient and clear.

5

Advanced

Addopts with multiple config files

🤔Before reading on: If both pytest.ini and setup.cfg have addopts, which one applies? Commit your guess.

Concept: Pytest merges config files but addopts from the first found config file is used exclusively.

Pytest searches config files in order: pytest.ini, tox.ini, then setup.cfg. For addopts, only the first file found with addopts is used. Others are ignored for addopts but used for other settings. This means addopts in pytest.ini overrides addopts in setup.cfg if both exist.

Result

Only one addopts setting applies, avoiding conflicts but requiring careful config management.

Understanding config file precedence prevents confusing test behaviors in complex projects.

6

Expert

Surprising effects of addopts on plugins

🤔Before reading on: Do you think addopts affects pytest plugins the same way as core pytest options? Commit your answer.

Concept: Addopts applies to all pytest options, including those from plugins, which can cause unexpected behavior.

Plugins add their own command-line options. If you put plugin options in addopts, they run every time. For example, a coverage plugin option in addopts means coverage runs on every test run, which might slow tests or cause side effects. Sometimes this is desired, sometimes not.

Result

Addopts can enable or disable plugin features globally, which can surprise users if not documented.

Knowing addopts affects plugins helps avoid hidden test slowdowns or unexpected reports.

Under the Hood

When pytest starts, it looks for config files in the current directory and parent directories. It reads the [pytest] section and extracts addopts as a string of options. These options are parsed as if typed on the command line before actual command-line arguments. This sets default flags and parameters for the test session. Command-line arguments then override these defaults. Internally, pytest uses a command-line parser that merges addopts and actual arguments to build the final configuration.

Why designed this way?

Addopts was designed to reduce repetitive typing and enforce consistent test runs across teams. It uses config files to keep settings close to the codebase, making tests portable. The override priority allows flexibility for special runs without changing config files. This balance between defaults and overrides was chosen to support both automation and manual testing needs.

┌───────────────┐
│ Start pytest  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Find config   │
│ files (pytest.ini, tox.ini, setup.cfg) │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Read [pytest] │
│ section       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Extract addopts│
│ string        │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Parse addopts  │
│ as CLI args   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Merge with    │
│ actual CLI    │
│ arguments     │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Run tests with │
│ final options  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does addopts override command-line options or vice versa? Commit to your answer.

Common Belief: Addopts options always override command-line options because they are in config files.

Reality: Command-line options always override addopts settings to allow temporary changes.

Why it matters: Believing addopts overrides CLI can cause confusion when tests don't behave as expected after passing different options.

Quick: Can you put any pytest option in addopts? Commit your guess.

Common Belief: You can put any pytest option in addopts, including test selectors like '-k'.

Reality: While possible, putting frequently changing options like '-k' in addopts is discouraged because it makes running specific tests harder.

Why it matters: Misusing addopts for dynamic options reduces flexibility and can cause accidental test runs.

Quick: If you have addopts in both pytest.ini and setup.cfg, which one applies? Commit your answer.

Common Belief: Addopts from all config files combine together.

Reality: Only the addopts from the first config file found is used; others are ignored for addopts.

Why it matters: Assuming addopts combine can cause unexpected test options and confusion in multi-config projects.

Quick: Does addopts affect pytest plugins the same way as core options? Commit your answer.

Common Belief: Addopts only affects core pytest options, not plugins.

Reality: Addopts applies to all options, including plugins, which can cause unexpected plugin behavior if not managed carefully.

Why it matters: Ignoring plugin options in addopts can lead to hidden test slowdowns or side effects.

Expert Zone

1

Addopts options are parsed before actual command-line arguments, so understanding this order is key to debugging option conflicts.

2

Some plugins add options that can drastically change test behavior when placed in addopts, so documenting these is critical in team projects.

3

Addopts can include environment variables or shell commands via pytest's ini interpolation, but this is rarely used and can cause subtle bugs.

When NOT to use

Addopts is not suitable for options that change frequently per test run, such as selecting specific tests or markers. For those, use command-line arguments or pytest's -k and -m options directly. Also, avoid putting options that require user interaction or dynamic values in addopts.

Production Patterns

In professional projects, addopts is used to enforce consistent verbosity, failure limits, and output formats across CI pipelines and developer machines. Teams often combine addopts with pytest plugins for coverage and reporting, ensuring all runs produce uniform results without extra commands.

Connections

Configuration Management

Addopts is a form of configuration management for test runs.

Understanding addopts helps grasp how software tools use config files to set defaults, a pattern common in many systems.

Command Line Interfaces (CLI)

Addopts merges config file options with CLI arguments.

Knowing how addopts and CLI options combine clarifies how programs prioritize user input versus defaults.

User Preferences in Software

Addopts stores user or project preferences for pytest behavior.

This shows how software remembers user choices to improve experience, similar to app settings or browser profiles.

Common Pitfalls

#1 Putting frequently changing test selectors in addopts.

Wrong approach:

[pytest]
addopts = -k test_login

# This forces pytest to always run only test_login.

Correct approach:

# Leave addopts for stable options
[pytest]
addopts = -v --maxfail=2

# Use command line for selectors
pytest -k test_login

Root cause:

Misunderstanding addopts as a place for all options instead of stable defaults.

#2 Expecting addopts in multiple config files to combine.

Wrong approach:

# pytest.ini
[pytest]
addopts = -v

# setup.cfg
[pytest]
addopts = --maxfail=1

# Expect both to apply.

Correct approach:

# Put all addopts in one config file, e.g., pytest.ini
[pytest]
addopts = -v --maxfail=1

Root cause:

Not knowing pytest uses only the first config file's addopts.

#3 Assuming addopts overrides command-line options.

Wrong approach:

# pytest.ini
[pytest]
addopts = --maxfail=1

# Running
pytest --maxfail=3
# Expect maxfail=1 to apply.

Correct approach:

# Command-line overrides addopts
pytest --maxfail=3
# maxfail=3 applies as expected.

Root cause:

Confusing default options with forced options.

Key Takeaways

Addopts lets you save default pytest command options in config files to avoid repetitive typing.

Command-line options always override addopts, allowing flexible test runs.

Addopts should hold stable, common options, not frequently changing test selectors.

Only the first config file with addopts is used, so manage configs carefully.

Addopts affects all pytest options, including plugins, which can impact test behavior.