pytest.ini

Overview

The `pytest.ini` file is a configuration file used by the **pytest** testing framework to customize and control the behavior of test discovery and execution within a project. It enables developers to specify default options, define test paths, configure plugins, set markers, and control various pytest features without needing to pass command-line arguments each time tests run.

This file typically resides at the root of the project directory and influences how pytest runs throughout the project lifecycle, ensuring consistent testing behavior across different development environments and CI pipelines.

Purpose and Functionality

Centralized pytest configuration: Enables defining global options and settings for pytest.
Test discovery control: Specifies which directories or files pytest should consider when searching for tests.
Custom markers: Allows defining and documenting custom markers that can be used to categorize or skip tests.
Plugin configuration: Configures third-party pytest plugins by passing options in a centralized manner.
Default command-line options: Sets default flags such as verbosity, test output format, and warnings handling.

Typical Contents of `pytest.ini`

While this file is empty in the provided content, a typical `pytest.ini` includes sections and keys such as:

[pytest]
minversion = 6.0
addopts = -ra -q
testpaths = tests
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    smoke: quick smoke tests

Explanation of Common Fields

Field	Description
`minversion`	Minimum pytest version required to run tests in this project
`addopts`	Default command line options added automatically when pytest runs
`testpaths`	List of directories to search for tests by default
`markers`	Defines custom markers for categorizing or skipping tests
`filterwarnings`	Controls warning filters (e.g., ignore or error on specific warnings)
`log_cli`	Enables logging output during test runs
`python_files`	Glob patterns for test file names (e.g., `test_*.py`)
`python_classes`	Glob patterns for test class names
`python_functions`	Glob patterns for test function names

How `pytest.ini` Interacts with the System

pytest Core: When you run pytest, it automatically looks for pytest.ini (or other config formats such as tox.ini or setup.cfg) in the current directory and parent directories to load configuration.
Test Discovery: Controls where and how tests are discovered, influencing which tests are run.
Plugins: Many pytest plugins read their configuration from this file, enabling seamless integration.
Continuous Integration: Ensures that tests run consistently across local developer machines and CI/CD servers by standardizing pytest options.

Implementation Details and Best Practices

The file uses INI format — simple key-value pairs grouped into sections.
It is read-only during test execution; it only defines settings.
Custom markers defined here should be documented to avoid warnings.
Avoid setting conflicting options both in pytest.ini and command line; command line options override pytest.ini.
Keep the file at the root of the project for consistent test discovery.
For advanced configuration, combine pytest.ini with other pytest hook files or plugins.

Example Usage

**Example `pytest.ini` file:**

[pytest]
minversion = 6.0
addopts = -v --maxfail=3 --disable-warnings
testpaths = tests integration_tests
markers =
    smoke: quick smoke tests
    slow: slow running tests
    regression: regression tests

**How this affects pytest runs:**

Only tests inside tests and integration_tests folders will be discovered.
Verbose output (-v) is enabled by default.
Test run will stop after 3 failures.
Warnings are suppressed during test runs.
Custom markers smoke, slow, and regression are available for selective test execution.

Visual Diagram: pytest.ini Configuration Impact Flowchart

flowchart TD
    A[pytest.ini file] --> B[pytest test runner]
    B --> C{Load Configuration}
    C --> D[Set test discovery paths]
    C --> E[Apply default CLI options]
    C --> F[Register custom markers]
    C --> G[Configure plugins]
    B --> H[Discover tests based on config]
    H --> I[Execute tests]
    I --> J[Produce test reports]

Summary

`pytest.ini` is a critical file for controlling pytest’s behavior in a project. While it contains no code, its configuration directives significantly influence test discovery, execution, and reporting. Proper setup of this file ensures consistent, efficient, and maintainable testing workflows, especially in teams and CI/CD environments.

If you require a more detailed example or integration with other pytest-related files (like [conftest.py](/projects/286/67243) or plugin configs), please provide those files or specify the use case.