Home

pytest-poolwatch

pytest-poolwatch shows whether a pytest concurrency pool stayed full while runnable tests were still queued.

It reconstructs real test overlap from public pytest reports and produces:

• peak and time-weighted average concurrency;
• utilization and idle slot-seconds;
• queued-work and active-test timelines;
• scheduler-underfill windows;
• terminal, JSON, and self-contained HTML reports.

PoolWatch is an observer. It does not replace pytest's runner, scheduler, or fixture lifecycle.

Start here

python -m pip install pytest-poolwatch
pytest --poolwatch --poolwatch-target=40

Or with uv:

uv add --dev pytest-poolwatch
uv run pytest --poolwatch --poolwatch-target=40

To save complete reports:

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

Documentation map

I want to…	Read
Run PoolWatch for the first time	Getting Started
Configure CLI and pyproject.toml options	Configuration
Understand utilization and underfill	Metrics and Diagnosis
Check runner and plugin support	Compatibility
Read terminal, HTML, and JSON output	Reports
Consume the versioned JSON format	JSON Report
Reproduce the scheduler bug that inspired the project	Examples
Understand the implementation	Architecture
Fix a surprising result	Troubleshooting
Contribute or run checks locally	Development
Publish a release	Release Guide
Learn why the project exists	Project Story
See possible future work	Roadmap

Version 0.1 scope

Version 0.1 measures concurrency, capacity, queue pressure, utilization, and scheduler underfill. It does not measure event-loop lag or attribute blocking calls. Those ideas are recorded on the roadmap without being presented as current features.

Source code: https://github.com/Butterski/pytest-poolwatch