Pytest Xdist Worker Stats

0.4.0 · active · verified Fri Apr 17

pytest-xdist-worker-stats is a pytest plugin that provides detailed statistics about individual worker performance after a pytest-xdist run, including test counts and execution times. The current version is 0.4.0, and it maintains an active, moderate release cadence.

Common errors

```
ModuleNotFoundError: No module named 'pytest_xdist_worker_stats'
```
cause Attempting to directly import the plugin into test files or conftest.py, or the plugin is not installed.

fix Pytest plugins are automatically discovered; direct imports are not typically needed. Ensure the plugin is installed via `pip install pytest-xdist-worker-stats`.
```
pytest: error: unrecognized arguments: --xdist-worker-stats
```
cause The `pytest-xdist-worker-stats` plugin is either not installed, or pytest cannot discover it in the current environment.

fix Verify installation by running `pip install pytest-xdist-worker-stats`. If it's installed, ensure your `pytest` command is executed within the same virtual environment where the plugin is installed.
```
No worker statistics output after running tests.
```
cause The `--xdist-worker-stats` command-line flag was not included when running pytest.

fix Rerun your pytest command, making sure to include the flag, e.g., `pytest -n auto --xdist-worker-stats`.
```
Failed to load plugin 'xdist-worker-stats': <class 'ModuleNotFoundError'>: No module named 'pytest_xdist'
```
cause The essential dependency `pytest-xdist` is not installed, which is required for this plugin to function and provide worker stats.

fix Install the `pytest-xdist` package: `pip install pytest-xdist`.

Warnings

gotcha This plugin requires `pytest-xdist` to be installed and active (by using the `-n` flag with pytest) to function correctly. Without `pytest-xdist`, there are no parallel workers to report statistics for.
Fix: Ensure `pip install pytest-xdist` is executed and pytest is run with a parallelization flag, e.g., `pytest -n auto`.
gotcha The worker statistics are only displayed when the `--xdist-worker-stats` command-line flag is explicitly used with pytest. Simply installing the plugin is not enough.
Fix: Always include `--xdist-worker-stats` in your pytest command, e.g., `pytest -n auto --xdist-worker-stats`.
breaking Version 0.4.0 introduces support for Pytest 9. Older versions of `pytest-xdist-worker-stats` may not be compatible with Pytest 9, and conversely, newer versions might introduce incompatibilities with significantly older Pytest versions (e.g., Pytest 7 or earlier).
Fix: Always keep `pytest-xdist-worker-stats` updated alongside `pytest` and `pytest-xdist` to ensure compatibility. Check release notes for specific version requirements.
gotcha The library requires Python 3.10 or newer. Running it with older Python versions will result in installation or runtime errors.
Fix: Ensure your environment uses Python 3.10 or a more recent version. Consider using `pyenv` or `conda` to manage Python versions.

Install

pip install pytest-xdist-worker-stats Install stable version

Imports

pytest-xdist-worker-stats
```
No direct import needed; pytest discovers plugins automatically.
```
Pytest plugins are designed for automatic discovery by pytest itself. Users typically do not need to import anything directly from 'pytest-xdist-worker-stats' in their test files or conftest.py.

Quickstart

This quickstart demonstrates how to use `pytest-xdist-worker-stats` by creating a simple test file with parameterized tests that will be run in parallel by `pytest-xdist`. The `--xdist-worker-stats` flag will activate the plugin and display the worker statistics after the test run.

import time
import pytest

@pytest.mark.parametrize("i", range(5))
def test_slow_task_a(i):
    time.sleep(0.1)

@pytest.mark.parametrize("i", range(3))
def test_slow_task_b(i):
    time.sleep(0.2)

# To run: save this as test_example.py, then run from your terminal:
# pip install pytest pytest-xdist pytest-xdist-worker-stats
# pytest -n 2 --xdist-worker-stats test_example.py

view raw JSON →