Compatibility

Compatibility

PoolWatch uses public pytest hooks and degrades conservatively when scheduler capacity cannot be established.

Support matrix

Runner or plugin	Status	Capacity handling	Timing source
pytest	Supported	Serial target 1	Pytest phase reports
pytest-asyncio	Supported	Serial test protocols	Pytest phase reports
pytest-xdist	Supported	Numeric workers; observed workers for auto	Controller reports with worker IDs
pytest-asyncio-cooperative	Supported by itself	max_asyncio_tasks	Scheduler-injected report timestamps
pytest-asyncio-concurrent	Conservative support	Explicit target or observed peak	Grouped phase reports
Custom scheduler	Supported with configuration	--poolwatch-target=N	Reports, then lifecycle-hook fallback
pytest-xdist + pytest-asyncio-cooperative	Unsupported combination	Do not combine	Overlapping runtest-loop implementations conflict

pytest

Ordinary pytest executes one test protocol at a time. PoolWatch uses target 1 and can still report phase durations, slow attempts, and serial utilization.

pytest-asyncio

pytest-asyncio runs async code inside a test but does not normally make multiple pytest test protocols concurrent. PoolWatch therefore treats it as serial unless another scheduler is responsible for concurrency.

pytest-xdist

For numeric -n values, PoolWatch uses the configured worker count. For values such as auto, it uses worker IDs observed in controller-side test reports.

Worker IDs are stored on individual test attempts and included in JSON output.

Different xdist distribution modes may intentionally leave workers unevenly loaded because of fixture scope, grouping, collection differences, or scheduler policy. PoolWatch reports the observed result; it does not replace xdist's scheduler.

pytest-asyncio-cooperative

When used without xdist, PoolWatch detects the plugin's max_asyncio_tasks setting and uses scheduler-provided pytest phase timestamps to reconstruct real overlap.

The repository's PR #86 and cloud-job examples use pinned cooperative versions to demonstrate a specific upstream refill bug and its fix.

Why xdist plus cooperative is unsupported

pytest-xdist and pytest-asyncio-cooperative both replace or control overlapping parts of pytest's runtest loop. Their file-level execution functions fight over the protocol, so the combined runner is not reliable independently of pytest-poolwatch.

If both plugins are installed, PoolWatch prefers an active xdist worker count instead of multiplying worker and cooperative limits. This avoids inventing a capacity such as 2 × 100 = 200, but it does not make the two schedulers compatible.

Use one scheduler at a time:

# xdist
pytest -n 8 --poolwatch

# cooperative async scheduling, without pytest-asyncio's plugin
pytest -p no:asyncio --max-asyncio-tasks=40 --poolwatch

pytest-asyncio-concurrent

Dynamic grouping does not always expose a single reliable global limit. PoolWatch uses observed peak as a baseline unless you pass an explicit target. Underfill diagnosis remains unavailable for an unknown target.

Custom schedulers

Use:

pytest --poolwatch --poolwatch-target=64

The scheduler should emit normal pytest reports with accurate start, stop, duration, when, outcome, and nodeid fields. Worker identity is optional.

Retries and incomplete attempts

PoolWatch numbers repeated protocols for a node ID as separate attempts. If only lifecycle start information exists when a session ends, the resulting interval is marked incomplete in JSON.

Operating systems and Python versions

The implementation is pure Python and declares operating-system independence. CI covers Python 3.11 through 3.14. The main unit and integration suite is runner-independent; scheduler example behavior can still vary with upstream plugin versions.