customize.rst

Overview

This file, **customize.rst**, serves as a comprehensive documentation guide for configuring the pytest testing framework via command line options and configuration files. It explains how pytest recognizes and processes configuration settings, the file formats supported, the algorithm pytest uses to determine the root directory (`rootdir`) and configuration file (`configfile`) for test discovery, and customization options for syntax highlighting themes.

The document is primarily aimed at users and plugin developers who want to understand or customize pytest behavior through configuration files or command line parameters. It clarifies how pytest merges and prioritizes settings from different configuration files and provides guidance on best practices and known caveats.

Detailed Explanations

Command Line Options and Configuration Files

pytest allows customization through both command line options and configuration files in INI-style format. By running:

pytest -h

users can view all available command line options and configuration file settings, including those registered by installed plugins.

Supported Configuration File Formats

pytest supports multiple configuration file formats, allowing users to specify settings such as minimum pytest version, additional command line options, and test paths.

The supported files, listed in order of precedence, are:

pytest.ini (or .pytest.ini)

Highest precedence, even if empty.
Example:

[pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

pyproject.toml (since pytest 6.0)
- Recognized if containing a [tool.pytest.ini_options] table.
- Example:
```
[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q"
testpaths = [
    "tests",
    "integration",
]
```
- Note: The use of ini_options is a transitional step toward a richer TOML configuration format.

tox.ini

Recognized if containing a [pytest] section.
Example:

[pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration

setup.cfg
- Recognized if containing a [tool:pytest] section.
- Example:
```
[tool:pytest]
minversion = 6.0
addopts = -ra -q
testpaths =
    tests
    integration
```
- Warning: Usage of setup.cfg for pytest configuration is discouraged except for very simple cases due to different parsing behavior that can lead to subtle bugs.

Initialization: Determining `rootdir` and `configfile`

pytest determines a root directory (`rootdir`) for each test session, used mainly to construct unique test *nodeids* and to provide a stable location for storing runtime caches and plugin data.

Key points:

rootdir is not used to modify Python import paths (sys.path or PYTHONPATH).
The --rootdir=path command line option overrides automatic rootdir detection but cannot be set in configuration files.
The selected configfile and rootdir are printed in the pytest header at startup.

Algorithm to Find `rootdir`:

If -c option is given, use that config file and its directory as rootdir.
Compute the common ancestor directory of the provided command line paths (args) that exist.
- If none exist, use the current working directory.
Search upwards from this directory for configuration files in this order:
- pytest.ini
- pyproject.toml (must contain [tool.pytest.ini_options])
- tox.ini (must contain [pytest])
- setup.cfg (must contain [tool:pytest])
If no config file found, look upwards for setup.py to determine rootdir.
If still no config file, search each argument path upwards for configuration files.
If no config file and no args, use current working directory as rootdir.

Only the first matching config file is used; multiple config files are never merged.

Attributes Available via `Config` Object

The pytest `Config` object exposes:

config.rootpath (pathlib.Path): The root directory for the test run.
config.inipath (pathlib.Path or None): The configuration file path used, if any.

These are modern replacements for the older `config.rootdir` and `config.inifile` attributes.

Builtin Configuration File Options

For a full list of options configurable via INI files, refer to the official pytest [ini options reference documentation](https://docs.pytest.org/en/stable/reference.html#ini-options-ref).

Syntax Highlighting Theme Customization

pytest supports customizing the syntax highlighting theme for test output via environment variables:

PYTEST_THEME: Specifies a Pygments style (e.g., monokai, colorful).
PYTEST_THEME_MODE: Specifies the theme mode, either light or dark.

Example usage:

export PYTEST_THEME=monokai
export PYTEST_THEME_MODE=dark
pytest

Usage Examples

Running pytest with a specific config file:

pytest -c mypytest.ini tests/

This will use `mypythest.ini` as the config file and its directory as `rootdir`.

Setting default options in pytest.ini:

[pytest]
addopts = -ra -q
testpaths = tests integration

Using pyproject.toml for configuration:

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-v"
testpaths = ["tests"]

Overriding rootdir manually:

pytest --rootdir=/path/to/project tests/

Important Implementation Details

The root directory detection algorithm is designed to ensure consistent test addressing and caching.
Only the first matching configuration file type in the search order is used; pytest does not merge multiple config files.
The pyproject.toml support is evolving; currently it supports a limited bridge table [tool.pytest.ini_options] but plans to use richer TOML features in the future.
The syntax highlighting customization leverages environment variables to allow flexible theming without modifying pytest code or configuration files.

Integration with Other System Components

This file documents configuration aspects of pytest, which affect how pytest collects and runs tests.
The Config object initialized based on these configurations is accessible by pytest plugins and fixtures (e.g., pytestconfig fixture), enabling plugins to adapt behavior to user settings.
The root directory and config file selection influence downstream actions such as test nodeid generation, cache storage, and plugin state management.
Interaction with external tools like tox is facilitated by allowing pytest settings inside tox.ini.
The environment variable based theme customization allows integration with CI systems or user environments without requiring code changes.

Mermaid Class Diagram

The document does not define classes or functions directly, but to illustrate the configuration and rootdir determination workflow, here is a flowchart representing the key steps and decision points:

flowchart TD
    A[Start: pytest invocation with args] --> B{Is -c option given?}
    B -- Yes --> C[Use -c config file and its dir as rootdir]
    B -- No --> D[Determine common ancestor dir of args or CWD]
    D --> E[Search upward for config files in order:\npytest.ini → pyproject.toml → tox.ini → setup.cfg]
    E --> F{Config file found?}
    F -- Yes --> G[Use config file dir as rootdir]
    F -- No --> H[Search upward for setup.py]
    H --> I{setup.py found?}
    I -- Yes --> J[Use setup.py dir as rootdir]
    I -- No --> K[Search args upward for config files]
    K --> L{Config file found?}
    L -- Yes --> M[Use config file dir as rootdir]
    L -- No --> N[Use common ancestor dir or CWD as rootdir]
    C --> O[Initialize Config object with rootdir and configfile]
    G --> O
    J --> O
    M --> O
    N --> O

Summary

This documentation file is a vital reference for understanding how pytest handles configuration through various file formats and command line options. It details the configuration precedence, root directory detection logic, and environment-based customization for syntax highlighting. The clear explanation of these mechanisms enables users and developers to configure pytest effectively and troubleshoot configuration-related issues.

For full configuration options and advanced usage, users should refer to the official pytest documentation and ini options reference.

End of **customize.rst** documentation.