The pytest.ini file is the central configuration file for Pytest, enabling you to modify the way tests are executed. Pytest locates and reads this file automatically and applies the specified settings during the execution of tests.

Location of pytest.ini

The pytest.ini file must typically be stored in the root directory of your project. Its name cannot be changed, and placing it elsewhere might prevent Pytest from recognizing it correctly.

Viewing Configuration Options

To see the available options for the pytest.ini file, you can execute pytest -h or pytest --help in the command line. The relevant section outlines a wide range of options you can use to customize Pytest behavior, such as marker definitions, warnings filters, directory traversal settings, logging configurations, and report personalization.

---

Common Configuration Options

Markers

Markers help categorize test cases, adding metadata to your tests. Without properly defining markers in the pytest.ini file, any usage of the @pytest.mark.<name> decorator will emit a warning.

• Syntax: Define markers using a list structure.
• Example Configuration:

# file: pytest.ini
[pytest]
markers =
    slow: identifies tests that focus on performance
    fast: labels tests that run quickly

---

xfail_strict

This setting enforces stricter behavior for the @pytest.mark.xfail decorator. When set to true, if a test marked as "expected to fail" passes, it will count as a failure.

• Values: Boolean (true or false) or integers (1 for true, 0 for false).
• Example Configuration:

# file: pytest.ini
[pytest]
xfail_strict = true

• Test Example:

# file: test_xfail_example.py
import pytest

class TestSample:
    @pytest.mark.xfail
    def test_example(self):
        value1 = "test"
        value2 = "test_value"
        assert value1 != value2

if __name__ == "__main__":
    pytest.main(["-s", "test_xfail_example.py"])

If xfail_strict is enabled, a passing test marked xfail will be flagged as failed. With the default setting (false), it would show "XPASS."

---

addopts

The addopts setting provides additional command-line options that are automatically applied whenever Pytest is executed. This is helpful for commands that frequently repeat, such as generating reports or rerunning failed tests.

• Example Configuration:

# file: pytest.ini
[pytest]
addopts = -v --reruns 2 --html=report.html --self-contained-html

After this setup, running pytest will automatically use the specified options without needing to manually type them each time.

---

log_cli

The log_cli parameter controls real-time display of logs in the console. This is especially useful for debugging purposes.

• Values: true or false (default), or numeric equivalents 1 and 0.
• Example Configuration:

# file: pytest.ini
[pytest]
log_cli = true

A true setting ensures logs are continuously displayed during test execution, detailing which tests passed or failed in real-time modules.

---

norecursedirs

When Pytest collects test files, it recursively traverses directories. You can exclude specific directories using the norecursedirs option.

• Example Configuration:

# file: pytest.ini
[pytest]
norecursedirs = env_cache temp_files

The directories env_cache and temp_files will be ignored during test collection.

---

Customizing Test Discovery Rules

Pytest uses default patterns to discover test files, classes, and functions (e.g., files named test_*.py). This behavior is configurable:

• Example Configuration:

# file: pytest.ini
[pytest]
testpaths = src_tests
python_files = *.check.py
python_classes = TestSuite*
python_functions = validate_*

Explanation:

• testpaths specifies the directory where Pytest should search for tests (src_tests in this example).
• python_files changes the file selection to match .check.py files.
• python_classes instructs Pytest to find classes that start with TestSuite.
• python_functions filters functions that begin with validate_.

This configuration changes the default discovery behavior to suit custom test naming and organization.