plugins.rst

Overview

The [plugins.rst](/projects/286/67291) file serves as a comprehensive guide for installing, using, managing, and troubleshooting third-party plugins within the pytest testing framework. It is primarily a documentation file (in reStructuredText format) that explains how pytest interacts with plugins, how users can extend pytest functionality by installing or writing their own plugins, and how to control plugin behavior during test runs.

This file does *not* contain executable code but acts as a critical user reference for plugin-related operations and configurations in pytest. It covers practical commands, configuration options, and best practices, making it an essential resource for pytest users who want to customize their test environment through plugins.

Detailed Explanations

Installing and Using Plugins

Purpose: Explains how to install/uninstall third-party plugins via pip.

Usage:

pip install pytest-NAME
pip uninstall pytest-NAME

Note: Once installed, pytest auto-discovers plugins without manual activation.
Example Plugins:
- pytest-django: Integration for Django apps testing.
- pytest-twisted: Support for Twisted apps with reactor and deferreds.
- pytest-cov: Coverage reporting compatible with distributed tests.
- pytest-xdist: Parallel and remote distributed test execution.
- And many others such as pytest-instafail, pytest-bdd, pytest-timeout, etc.
Additional Resources:
- Complete plugin list and compatibility status: referenced as plugin-list.
- PyPI search for pytest plugins: https://pypi.org/search/?q=pytest-

Requiring/Loading Plugins in Test Modules or conftest Files

Purpose: Shows how to explicitly require plugins in test code or configuration files.
Mechanism: Use the special global variable pytest_plugins:
```
pytest_plugins = ("myapp.testsupport.myplugin",)
```
Effect: When the test or conftest file loads, specified plugins load automatically.
Important Notes:
- Using pytest_plugins in non-root conftest.py files is deprecated.
- The name pytest_plugins is reserved and should not be used for custom modules.

Finding Active Plugins

Purpose: How to find which plugins are currently active during a pytest run.
Command:
```
pytest --trace-config
```
Output: Extended test header listing all active plugins and loaded local conftest.py files.

Deactivating / Unregistering Plugins by Name

Purpose: Prevent certain plugins from loading.
Command Line:
```
pytest -p no:NAME
```
Configuration File: Add to pytest.ini to disable plugin project-wide:
```
[pytest]
addopts = -p no:NAME
```
Environment Variable: Use PYTEST_ADDOPTS to conditionally disable plugins (e.g., in CI):
```
export PYTEST_ADDOPTS="-p no:NAME"
```
Relationship: The NAME corresponds to the plugin name discovered via --trace-config.

Disabling Plugin Autoloading

Purpose: Disable pytest's automatic discovery of plugins.
Use Case: If you prefer to manually specify plugins to load.

Options:

Environment Variable:

export PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
export PYTEST_PLUGINS=NAME,NAME2
pytest

Command Line:

pytest --disable-plugin-autoload -p NAME -p NAME2

pytest.ini:

[pytest]
addopts =
    --disable-plugin-autoload
    -p NAME
    -p NAME2

Version Added: Flag --disable-plugin-autoload introduced in pytest 8.4.

Important Implementation Details and Algorithms

Since this is a documentation file, it contains no executable code or algorithms. However, it documents key concepts and mechanisms by which pytest manages plugins:

Automatic Plugin Discovery: pytest automatically detects plugins installed in the environment, integrating them without explicit user action.
Plugin Loading Order and Control: Users can control which plugins load via environment variables, command-line flags, or configuration files.
Plugin Activation and Deactivation: The -p option allows enabling or disabling plugins dynamically.
Plugin Naming and Identification: Plugins are identified by names typically derived from their package names (e.g., pytest-cov as cov).

Interactions with Other Parts of the System

pytest CLI: The documented commands and flags integrate directly with the pytest command-line interface.
pytest Configuration Files (pytest.ini, tox.ini, setup.cfg): Plugin management options can be persisted here.
conftest.py Files: Local pytest plugins or test-specific plugin requirements are specified in these files.
Python Environment / Package Manager: Plugins are installed/uninstalled via pip.
pytest Plugin Discovery Mechanism: The documentation explains how pytest discovers and manages plugins at runtime.
Writing Plugins: This documentation references a separate section (writing-plugins) for developing custom plugins.

Usage Examples

Install a plugin:
```
pip install pytest-cov
```
Run pytest with a plugin disabled:
```
pytest -p no:cov
```
Require a plugin in a test module:
```
pytest_plugins = ("my_custom_plugin",)
```
See which plugins are active:
```
pytest --trace-config
```
Disable automatic plugin loading and specify plugins manually:
```
pytest --disable-plugin-autoload -p cov -p xdist
```

Visual Diagram: Plugin Management Flowchart

flowchart TD
    A[Start pytest run] --> B{Is plugin autoload enabled?}
    B -- Yes --> C[Discover installed plugins automatically]
    B -- No --> D[Load plugins specified via -p or PYTEST_PLUGINS]
    C --> E[Load discovered plugins]
    D --> E
    E --> F{Are there plugins disabled by -p no:NAME or config?}
    F -- Yes --> G[Prevent loading of specified plugins]
    F -- No --> H[All plugins loaded]
    G --> H
    H --> I[Execute tests with active plugins]
    I --> J[End]

Summary

The [plugins.rst](/projects/286/67291) file is essential user documentation for managing pytest plugins. It details installation, activation, deactivation, and discovery mechanisms for plugins, supported by practical commands, environment variable usage, and configuration file options. This resource empowers users to customize their testing environment efficiently and troubleshoot plugin-related issues effectively.

By following the guidelines and examples in this file, pytest users can leverage the extensive ecosystem of plugins to enhance test automation, reporting, parallelization, and integration with other frameworks or tools.