Troubleshooting

Troubleshooting

--poolwatch is unknown

Confirm that the package is installed in the same environment that runs pytest:

python -m pip show pytest-poolwatch
python -m pytest --help

With uv, run pytest through the project environment:

uv run pytest --help

No PoolWatch summary appears

PoolWatch must be enabled by at least one of:

• --poolwatch;
• poolwatch = true in pytest configuration;
• a JSON path;
• an HTML path.

A target by itself does not enable collection.

Underfill diagnosis is unavailable

PoolWatch could not establish a reliable capacity. Pass it explicitly:

pytest --poolwatch --poolwatch-target=40

The observed peak remains useful as a baseline, but it cannot prove that a higher known capacity was unused.

Utilization is greater than 100%

The configured target is lower than observed concurrency. Correct the target or check whether another scheduler is active.

Inspect loaded plugins with:

pytest --trace-config

xdist reports an unexpectedly large target

Do not combine pytest-xdist and pytest-asyncio-cooperative. They have overlapping runtest-loop implementations and are unsupported together.

Current PoolWatch versions prefer the xdist worker count when both plugins are installed. If a prior version multiplied worker and cooperative limits, upgrade and run only one scheduler.

pytest or xdist raises an internal runtest error

First disable pytest-asyncio-cooperative and retry:

pytest -p no:asyncio-cooperative -n 2

If the error disappears, the conflict is between scheduler plugins rather than PoolWatch's report analysis.

Cooperative examples emit pytest deprecation warnings

The pinned upstream cooperative plugin uses a pytest API scheduled for removal. The repository's stress command filters that known warning so its output remains readable. PoolWatch itself supports pytest below version 10.

JSON or HTML is missing

Look for a PytestWarning explaining the operating-system write error. Check:

• parent-directory permissions;
• whether another process owns the destination;
• whether a relative path resolved against the expected pytest root;
• available disk space.

Artifact write failures do not replace pytest's original exit status.

Collected and observed counts differ

Possible reasons include:

• collection-only or interrupted sessions;
• a test excluded with poolwatch_ignore;
• retries, which create multiple attempts;
• a worker or process terminating before reports arrive.

Inspect the incomplete flag on JSON test attempts.

Phase totals exceed the session duration

This is expected in concurrent runs. Phase totals aggregate work across tests; wall-clock duration measures elapsed time. Overlapping call phases can sum to far more than wall time.

A test waits on an API but still counts as active

PoolWatch observes pytest test intervals. It cannot currently distinguish CPU work, async waiting, external I/O, or event-loop blocking inside an active test. See Roadmap for possible progress and loop-lag measurements.

Still stuck?

Open a reproducible issue: https://github.com/Butterski/pytest-poolwatch/issues

Include pytest and plugin versions, the command, target configuration, runner, and a minimal JSON report when it is safe to share.