Reports

Reports

PoolWatch has one renderer-independent report model and three output formats. All formats describe the same analyzed session.

Terminal summary

Enable it with:

pytest --poolwatch

Example:

============================= PoolWatch summary =============================
Configured concurrency:                 40
Target source:                command_line
Peak active tests:                      40
Average active tests:                 32.60
Concurrency utilization:             81.5%
Scheduler underfill:                17m 23s
Peak queued tests:                     126
Idle slot-seconds:                 4,912.00

If underfill is present, the terminal report also shows the longest window's minimum active count, maximum queue, duration, and a conservative likely cause.

If capacity is unknown, it explains that --poolwatch-target=N is required for a definitive diagnosis.

JSON report

pytest --poolwatch-json=.poolwatch/run.json

JSON output includes:

• schema and generation metadata;
• session counts and observed duration;
• target source and confidence;
• aggregate summary metrics;
• underfill windows;
• active and queued timeline points;
• every observed test attempt and its pytest phases.

See JSON Report for field definitions and compatibility rules.

HTML report

pytest --poolwatch-html=.poolwatch/run.html

The generated file is self-contained: no JavaScript bundle, stylesheet, font, image, or network service is required. It contains:

• summary metric cards;
• active tests over time with the configured target;
• queued tests over time;
• scheduler-underfill windows;
• aggregate setup, call, and teardown duration;
• the ten slowest observed attempts.

Node IDs and other dynamic strings are HTML-escaped.

Writing both formats

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

Specifying either report path enables PoolWatch automatically.

Atomic writes

PoolWatch creates the parent directory, writes a sibling temporary file, and then replaces the final path. A successful report is therefore never exposed as a partially written file.

If the operating system rejects a write, PoolWatch emits a pytest warning. It does not replace the test session's original exit code with an artifact error.

CI artifacts

A typical GitHub Actions step:

- name: Run tests with PoolWatch
  run: >-
    pytest --poolwatch --poolwatch-target=16
    --poolwatch-json=.poolwatch/ci.json
    --poolwatch-html=.poolwatch/ci.html

- name: Upload PoolWatch reports
  if: always()
  uses: actions/upload-artifact@v7
  with:
    name: poolwatch-report
    path: .poolwatch/

Retain JSON when you need automated comparisons. Upload HTML for human inspection after a surprising CI run.

Comparing runs

Wall time and utilization depend on the machine and workload. Prefer invariants for automated checks:

• expected collected and observed attempt counts;
• expected configured capacity;
• expected peak for a controlled workload;
• no incomplete intervals;
• no material underfill above a deliberately chosen threshold.

The example checkers in the source repository follow this approach rather than hard-coding machine-specific duration bounds.