Getting Started

Getting Started

Requirements

• Python 3.11 or newer
• pytest 8.2 or newer, below pytest 10

PoolWatch has no runtime dependency other than pytest.

Install

With pip:

python -m pip install pytest-poolwatch

With uv:

uv add --dev pytest-poolwatch

The distribution registers a pytest11 entry point. Once installed, pytest loads it automatically; no conftest.py entry is required.

Verify discovery:

pytest --help

The output should contain a poolwatch option group.

First run

For ordinary serial pytest:

pytest --poolwatch

For a scheduler whose capacity PoolWatch cannot infer, pass the expected number of concurrently active tests:

pytest --poolwatch --poolwatch-target=40

At session end, PoolWatch prints a summary after the standard pytest result.

Save reports

JSON or HTML output enables PoolWatch even when --poolwatch is omitted:

pytest \
  --poolwatch-target=40 \
  --poolwatch-json=.poolwatch/run.json \
  --poolwatch-html=.poolwatch/run.html

• JSON is intended for CI, scripts, and historical comparison.
• HTML is a self-contained report that can be opened locally or uploaded as a CI artifact.

Parent directories are created automatically. Files are written atomically by replacing a temporary file only after the complete report is ready.

Choose the target carefully

The target is the maximum number of tests the active scheduler is expected to run concurrently. It is not necessarily the number of CPU cores.

• pytest -n 8: target 8, detected from xdist.
• --max-asyncio-tasks=40: target 40 when pytest-asyncio-cooperative is used by itself.
• a custom async scheduler with 100 slots: pass --poolwatch-target=100.
• ordinary pytest or pytest-asyncio: serial target 1.

Without a reliable target, PoolWatch can report observed concurrency but will not claim definitive scheduler underfill.

Exclude a test

Use poolwatch_ignore for work that should not participate in the concurrency metrics:

import pytest


@pytest.mark.poolwatch_ignore
def test_one_off_migration():
    ...

The test still runs normally; it is excluded only from PoolWatch collection and analysis.

poolwatch_blocking is currently a documentation marker. Version 0.1 does not measure event-loop responsiveness or use this marker in calculations.

Next steps

• Configuration for every option and precedence rule.
• Metrics and Diagnosis before interpreting underfill.
• Compatibility when another plugin controls test execution.
• Reports to consume terminal, HTML, or JSON output.