JSON Report

JSON Report

Generate a report with:

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

Versioning policy

The top-level schema_version is currently 1.

Within schema version 1:

• new fields may be added compatibly;
• existing fields retain their meaning;
• removing a field or changing its meaning requires a schema-version bump.

Consumers should ignore unknown fields and validate the schema version before processing a report.

Top-level shape

{
  "schema_version": 1,
  "generated_at": "2026-07-29T12:00:00Z",
  "exit_status": 0,
  "session": {},
  "target": {},
  "summary": {},
  "underfill_windows": [],
  "timeline": [],
  "tests": []
}

All relative timestamps and durations are seconds. Serialized floating-point values are rounded to six decimal places.

session

Field	Type	Meaning
collected_tests	integer	Unique non-ignored tests represented as workload.
observed_test_attempts	integer	Finalized attempts; may exceed unique tests after retries.
duration_seconds	number	Earliest observed start to latest observed finish.

target

Field	Type	Meaning
configured	integer or null	Known capacity used for definitive diagnosis.
effective	integer	Capacity used for utilization rendering and baseline metrics.
source	string	Command line, pytest config, detected plugin, or fallback description.
confidence	string	explicit, detected, or fallback.

When configured is null, underfill diagnosis is disabled.

summary

Field	Type	Meaning
peak_active_tests	integer	Maximum overlapping attempts.
average_active_tests	number	Time-weighted active-test average.
concurrency_utilization	number	Fraction of configured slot-time used.
scheduler_underfill_seconds	number	Sum of retained underfill-window durations.
idle_slot_seconds	number	Total unused capacity area, including drain.
peak_queued_tests	integer	Maximum not-yet-started queue represented in the timeline.
phase_duration_seconds	object	Aggregate duration keyed by pytest phase name.

concurrency_utilization is a fraction: 0.815 means 81.5%.

underfill_windows

Each entry contains:

Field	Type	Meaning
started_at_seconds	number	Offset from the report origin.
finished_at_seconds	number	Offset from the report origin.
duration_seconds	number	Window duration.
minimum_active_tests	integer	Lowest active count within the merged window.
maximum_queued_tests	integer	Highest queue count within the merged window.
idle_slot_seconds	number	Unused capacity area within this window.

Only windows meeting the configured underfill threshold are serialized.

timeline

Each point represents state immediately after every event at its timestamp was applied:

{
  "at_seconds": 1.25,
  "active_tests": 38,
  "queued_tests": 126
}

Interpret values as a step function lasting until the next point.

tests

Each attempt contains:

Field	Type	Meaning
nodeid	string	Pytest node ID.
attempt	integer	One-based attempt number for the node ID and worker.
worker	string	xdist worker ID or main.
started_at_seconds	number	Offset from the first observed test start.
finished_at_seconds	number	Offset from the first observed test start.
duration_seconds	number	Complete observed attempt duration.
outcome	string	Derived attempt outcome.
incomplete	boolean	True when report phases were unavailable and session end closed the interval.
phases	array	Observed setup, call, and teardown phase summaries.

Each phase contains name, duration_seconds, and outcome.

Minimal consumer

from __future__ import annotations

import json
from pathlib import Path


payload = json.loads(Path(".poolwatch/run.json").read_text(encoding="utf-8"))
if payload["schema_version"] != 1:
    raise RuntimeError("unsupported PoolWatch schema")

summary = payload["summary"]
print(f"utilization: {summary['concurrency_utilization']:.1%}")
print(f"underfill: {summary['scheduler_underfill_seconds']:.3f}s")

For CI, prefer validating behavioral invariants over exact wall-clock values. See Examples for report checkers used by the repository.