pytest.ini configuration - Deep Dive

Overview - pytest.ini configuration

What is it?

pytest.ini configuration is a special file used to set up and customize how pytest runs tests. It lets you define options like which tests to run, how to show output, and other settings without typing them every time. This file is written in a simple format and placed in your project folder. It helps make testing easier and more consistent.

Why it matters

Without pytest.ini, you would have to type all your test options every time you run pytest, which is slow and error-prone. This file saves time and avoids mistakes by remembering your preferences. It also helps teams share the same testing setup, so everyone runs tests the same way. Without it, tests might behave differently on different computers, causing confusion and bugs.

Where it fits

Before learning pytest.ini, you should know basic pytest commands and how to write simple tests. After mastering pytest.ini, you can explore advanced pytest features like hooks, plugins, and custom markers to further control test behavior.

Mental Model

Core Idea

pytest.ini is a project-level settings file that tells pytest how to behave every time it runs tests in that project.

Think of it like...

It's like a recipe card you keep in your kitchen that lists your favorite way to bake a cake, so you don't have to remember all the steps each time.

┌───────────────┐
│ pytest.ini    │
├───────────────┤
│ [pytest]      │
│ addopts=...   │
│ markers=...   │
│ testpaths=... │
└───────────────┘
       ↓
┌─────────────────────────┐
│ pytest test runner reads │
│ settings and runs tests  │
└─────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is pytest.ini file

Concept: Introducing the pytest.ini file as a configuration file for pytest.

pytest.ini is a plain text file placed in your project folder. It uses a simple format with sections and key-value pairs. The main section is [pytest]. You write settings here to control pytest behavior, like which tests to run or how to show output.

Result

You have a file named pytest.ini in your project root that pytest will read automatically when you run tests.

Understanding that pytest.ini is just a simple file that pytest reads every time helps you see how you can control test runs without typing long commands.

2

Foundation

Basic structure of pytest.ini

Concept: Learning the format and common keys inside pytest.ini.

The pytest.ini file starts with [pytest] section header. Below it, you add options like addopts, testpaths, markers, and others. For example: [pytest] addopts = -v testpaths = tests markers = slow This tells pytest to run tests verbosely, look for tests in the 'tests' folder, and recognize a 'slow' marker.

Result

You can write a simple pytest.ini that changes how pytest runs and finds tests.

Knowing the structure and common keys lets you customize pytest easily and consistently across your project.

3

Intermediate

Using addopts to customize test runs

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

Concept: addopts lets you add command-line options inside pytest.ini so you don't have to type them every time.

addopts is a key where you write options exactly as you would on the command line. For example: addopts = -v --maxfail=2 --tb=short This runs tests verbosely, stops after 2 failures, and shows short tracebacks. You can combine many options here.

Result

pytest runs with your preferred options automatically, saving time and avoiding mistakes.

Understanding addopts means you can automate your test preferences and avoid repeating long commands.

4

Intermediate

Defining and using markers in pytest.ini

🤔Before reading on: do you think markers need to be declared in pytest.ini before use? Commit to your answer.

Concept: Markers are labels you put on tests to group or select them. Declaring them in pytest.ini helps pytest recognize and document them.

In pytest.ini, you declare markers like this: markers = slow: marks tests as slow smoke: marks smoke tests Then in your test code, you use @pytest.mark.slow or @pytest.mark.smoke. This helps pytest avoid warnings and lets you run tests by marker, e.g., pytest -m slow.

Result

Markers are officially registered, making test selection and documentation clearer.

Knowing to declare markers prevents warnings and helps organize tests better.

5

Intermediate

Specifying test discovery paths

Concept: testpaths tells pytest where to look for tests, overriding default search locations.

By default, pytest looks for tests in the current folder and subfolders. You can specify folders explicitly: [pytest] testpaths = tests integration This tells pytest to only look inside 'tests' and 'integration' folders for test files.

Result

pytest runs faster and more focused by searching only specified folders.

Controlling test discovery paths helps manage large projects and speeds up test runs.

6

Advanced

Configuring pytest.ini for parallel testing

🤔Before reading on: do you think pytest.ini alone can enable parallel test runs? Commit to your answer.

Concept: pytest.ini can include options to configure plugins like pytest-xdist for parallel testing.

If you install pytest-xdist, you can add options in pytest.ini: [pytest] addopts = -n 4 This runs tests on 4 CPU cores in parallel. You can also add other options to control load balancing or grouping.

Result

Tests run faster by using multiple CPU cores automatically when you run pytest.

Knowing how to configure plugins via pytest.ini unlocks powerful test speed improvements.

7

Expert

Overriding pytest.ini with other config files

🤔Before reading on: do you think pytest.ini is the only config file pytest reads? Commit to your answer.

Concept: pytest supports multiple config files like tox.ini and setup.cfg that can override or complement pytest.ini settings.

pytest reads config files in this order: 1. pytest.ini 2. tox.ini 3. setup.cfg Settings in later files override earlier ones. This lets you organize configs by tool or environment. For example, tox.ini might hold pytest options for CI, while pytest.ini holds local options.

Result

You can manage complex projects with layered configs, avoiding conflicts and duplication.

Understanding config file precedence helps avoid confusion and bugs in large projects with multiple tools.

Under the Hood

When you run pytest, it looks for configuration files in the current directory and parent directories. pytest.ini is parsed first if found. The file is read as an INI format, extracting the [pytest] section and its keys. These keys set internal pytest options before tests start. This means pytest behavior is influenced before any test code runs, ensuring consistent setup.

Why designed this way?

pytest.ini was designed as a simple, human-readable file to make configuration easy and shareable. Using the INI format leverages a common standard understood by many tools. Supporting multiple config files allows flexibility for different environments and tools. This design balances simplicity with power, avoiding complex config languages.

┌───────────────┐
│ Run pytest    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Look for config│
│ files in order │
│ pytest.ini     │
│ tox.ini        │
│ setup.cfg      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Parse INI file │
│ Extract [pytest]│
│ options        │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Apply options │
│ to pytest run │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Run tests     │
└───────────────┘

Myth Busters - 4 Common Misconceptions

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

Common Belief: pytest.ini settings always override command-line options.

Reality: Command-line options always override pytest.ini settings if both specify the same option.

Why it matters: If you expect pytest.ini to override command-line flags, you might be confused when your command-line options don't take effect.

Quick: Do you think pytest.ini must be in the root folder only? Commit to your answer.

Common Belief: pytest.ini must be placed only in the root folder of the project.

Reality: pytest.ini can be in any folder pytest runs from, and pytest searches parent folders up to the root. The closest pytest.ini to the current directory is used.

Why it matters: Placing pytest.ini in the wrong folder might cause pytest to ignore it, leading to unexpected test behavior.

Quick: Do you think markers work without declaring them in pytest.ini? Commit to your answer.

Common Belief: You can use any marker in tests without declaring it in pytest.ini.

Reality: pytest warns about unknown markers unless they are declared in pytest.ini or other config files.

Why it matters: Ignoring marker declarations causes warning messages and can confuse team members about test categorization.

Quick: Does pytest.ini support all pytest command-line options? Commit to your answer.

Common Belief: All pytest command-line options can be set in pytest.ini.

Reality: Not all command-line options are supported in pytest.ini; some must be passed on the command line.

Why it matters: Trying to set unsupported options in pytest.ini leads to silent failures or ignored settings.

Expert Zone

1

pytest.ini settings are cached by pytest, so changes may require restarting the test session or clearing caches to take effect.

2

Some plugins add their own configuration keys to pytest.ini, which can be combined with core pytest options for powerful customization.

3

pytest.ini can include environment variables in some options, but this behavior depends on pytest version and plugins.

When NOT to use

pytest.ini is not suitable when you need dynamic or per-run configuration changes. In such cases, use command-line options or pytest hooks in conftest.py. For very complex setups, consider using tox or other CI tools to manage test environments.

Production Patterns

In professional projects, pytest.ini is used to enforce consistent test runs across developers and CI systems. Teams declare markers for test categories like smoke, regression, or slow tests. They also configure plugins like coverage or xdist here. Often, pytest.ini is combined with tox.ini to separate local and CI configurations.

Connections

Continuous Integration (CI) pipelines

pytest.ini configures pytest behavior that CI pipelines rely on for consistent test runs.

Knowing pytest.ini helps ensure tests run the same way locally and in automated CI environments, preventing 'works on my machine' problems.

INI file format

pytest.ini uses the INI file format, a simple key-value configuration style used by many tools.

Understanding INI files helps you read and write pytest.ini and other config files like tox.ini or setup.cfg.

Software configuration management

pytest.ini is an example of managing software behavior through configuration files.

Recognizing pytest.ini as configuration management shows how software behavior can be controlled without changing code, a key DevOps practice.

Common Pitfalls

#1 Placing pytest.ini in a subfolder where pytest is not run from.

Wrong approach:

Project/
src/
tests/
pytest.ini

Running pytest from Project folder ignores pytest.ini in tests.

Correct approach:

Project/
pytest.ini
src/
tests/

Place pytest.ini in the root or folder where pytest is run.

Root cause:

pytest only reads config files from the current directory or parents, so placing pytest.ini too deep makes it invisible.

#2 Not declaring custom markers in pytest.ini.

Wrong approach:

[pytest]

# no markers declared

# test code uses @pytest.mark.slow

Correct approach:

[pytest]
markers =
slow: marks tests as slow

Root cause:

pytest warns about unknown markers unless declared, so forgetting this causes noisy warnings.

#3 Trying to set unsupported command-line options in pytest.ini addopts.

Wrong approach:

[pytest]
addopts = --some-unsupported-option

Correct approach:

[pytest]
addopts = -v --maxfail=1

Root cause:

Not all command-line options are valid in addopts; unsupported ones are ignored silently.

Key Takeaways

pytest.ini is a simple text file that configures pytest behavior for your project.

It saves time and ensures consistency by storing common options and markers in one place.

pytest.ini uses the INI format with a [pytest] section and keys like addopts and markers.

Command-line options override pytest.ini settings, so you can still customize runs temporarily.

Understanding pytest.ini helps you manage tests better, especially in teams and CI environments.

Practice

1. What is the primary purpose of the pytest.ini file in a pytest project?

easy

A. To install pytest dependencies automatically

B. To store configuration settings for pytest test runs

C. To write test functions and test cases

D. To generate test reports after running tests

Solution

1. Step 1: Understand pytest.ini role

   The pytest.ini file is used to configure pytest behavior before running tests.

2. Step 2: Differentiate from other files

   Test functions are written in Python files, not in pytest.ini. Dependency installation and report generation are handled elsewhere.

3. Final Answer:

   To store configuration settings for pytest test runs -> Option B

4. Quick Check:

   pytest.ini = config file [OK]

Hint: pytest.ini holds settings, not test code or reports [OK]

Common Mistakes:

• Confusing pytest.ini with test script files
• Thinking pytest.ini installs packages
• Assuming pytest.ini generates reports

2. Which of the following is the correct way to set the verbosity level to 2 in pytest.ini?

easy

A. [pytest]
addopts = -vv

B. [pytest]
verbosity = 2

C. [pytest]
verbosity: 2

D. [pytest]
addopts = --verbosity=2

Solution

1. Step 1: Recall pytest verbosity setting

   pytest uses addopts to pass command-line options like -vv for verbosity level 2.

2. Step 2: Check syntax correctness

   [pytest] addopts = -vv correctly uses addopts = -vv. [pytest] verbosity = 2 uses an invalid key verbosity. [pytest] verbosity: 2 uses wrong syntax with colon. [pytest] addopts = --verbosity=2 uses an invalid flag.

3. Final Answer:

   [pytest] addopts = -vv -> Option A

4. Quick Check:

   Verbosity level 2 via addopts = -vv [OK]

Hint: Use addopts with -vv for verbosity level 2 in pytest.ini [OK]

Common Mistakes:

• Using 'verbosity' instead of 'addopts'
• Incorrect syntax with colon instead of equals
• Using unsupported flags like --verbosity

3. Given this pytest.ini content:

[pytest]
markers = slow: marks tests as slow
          smoke: marks smoke tests
addopts = -rs

What will be the effect of running pytest with this configuration?

medium

A. Tests marked as slow or smoke will be skipped automatically

B. pytest will run tests with no output

C. Only tests marked as slow will run

D. pytest will show extra summary info for skipped and failed tests

Solution

1. Step 1: Understand markers and addopts

   The markers section defines labels for tests but does not skip them automatically. The addopts = -rs option tells pytest to show extra summary info for skipped and failed tests.

2. Step 2: Analyze each option

   Tests marked as slow or smoke will be skipped automatically is wrong because markers alone don't skip tests. Only tests marked as slow will run is wrong because no selection is made. pytest will run tests with no output is wrong because -rs increases output detail.

3. Final Answer:

   pytest will show extra summary info for skipped and failed tests -> Option D

4. Quick Check:

   addopts = -rs shows skip/fail summary [OK]

Hint: addopts = -rs shows skip and fail summaries [OK]

Common Mistakes:

• Thinking markers skip tests automatically
• Confusing addopts flags with test selection
• Assuming no output with -rs option

4. You added this to your pytest.ini file:

[pytest]
markers = regression
addopts = --maxfail=3

But when you run pytest, you get an error: ERROR: unknown option: --maxfail=3
What is the most likely cause?

medium

A. The addopts line should use -maxfail=3 instead

B. The pytest.ini file is missing the [pytest] header

C. The pytest version is outdated and does not support --maxfail

D. Markers must be defined after addopts in pytest.ini

Solution

1. Step 1: Understand the error message

   The error says unknown option: --maxfail=3, meaning pytest does not recognize this option.

2. Step 2: Check possible causes

   The addopts line should use -maxfail=3 instead is wrong because --maxfail requires two dashes. The pytest.ini file is missing the [pytest] header is wrong because the header is present. Markers must be defined after addopts in pytest.ini is wrong because order does not matter. The most common cause is an outdated pytest version that lacks support for --maxfail.

3. Final Answer:

   The pytest version is outdated and does not support --maxfail -> Option C

4. Quick Check:

   Unknown option usually means outdated pytest [OK]

Hint: Unknown option often means pytest version too old [OK]

Common Mistakes:

• Changing option syntax incorrectly
• Forgetting to include [pytest] header
• Thinking order of keys matters in pytest.ini

5. You want to configure pytest.ini to:
1. Mark tests with slow and critical labels.
2. Run only tests matching the pattern test_*.py.
3. Stop after 2 failures.

Which of the following pytest.ini configurations achieves all three correctly?

hard

A. [pytest]
markers = slow: slow tests
critical: critical tests
python_files = test_*.py
addopts = --maxfail=2

B. [pytest]
markers = slow
critical
python_files = test_*.py
addopts = -x --maxfail=2

C. [pytest]
markers = slow: slow tests
critical: critical tests
python_files = test_*.py
addopts = -x --maxfail=2

D. [pytest]
markers = slow: slow tests
critical: critical tests
python_files = test_*.py
addopts = --maxfail=2 -x

Solution

1. Step 1: Check markers syntax

   Options A, C, and D correctly define markers with descriptions. [pytest] markers = slow critical python_files = test_*.py addopts = -x --maxfail=2 lacks descriptions, which is allowed but less clear.

2. Step 2: Verify test file pattern

   All options set python_files = test_*.py correctly.

3. Step 3: Confirm failure stop and run options

   [pytest] markers = slow: slow tests critical: critical tests python_files = test_*.py addopts = --maxfail=2 uses addopts = --maxfail=2 which stops after 2 failures but does not stop immediately on first failure. Options C and D add -x which stops after first failure, conflicting with requirement to stop after 2 failures. [pytest] markers = slow critical python_files = test_*.py addopts = -x --maxfail=2 lacks descriptions in markers.

4. Final Answer:

   Markers with descriptions, correct python_files, and stop after 2 failures -> Option A

5. Quick Check:

   Use --maxfail=2 without -x to stop after 2 failures [OK]

Hint: Use --maxfail=2 without -x to stop after 2 failures [OK]

Common Mistakes:

• Adding -x stops after 1 failure, not 2
• Omitting marker descriptions
• Misconfiguring python_files pattern