Roadmap

Roadmap

The roadmap records possible directions, not promises or release dates. New diagnostics should be based on evidence available through stable public APIs.

v0.1 — See the pool

Implemented:

• public-hook collection;
• setup, call, and teardown intervals;
• target-capacity configuration and conservative discovery;
• active and queued timelines;
• peak and average concurrency;
• utilization and idle slot-seconds;
• scheduler-underfill detection with a noise threshold;
• terminal, schema-versioned JSON, and self-contained HTML reports;
• ignored-test marker;
• PR #86 regression and cloud-job stress examples;
• Python 3.11–3.14 CI and PyPI packaging.

Near-term hardening

Potential priorities:

• reduce collector lookup cost for very large suites;
• add more target-discovery tests for xdist auto, logical workers, and custom schedulers;
• detect and explain a target lower than observed peak;
• add report-size controls or timeline sampling for extremely large suites;
• publish stable JSON examples and consumer utilities;
• add more real-world scheduler regression fixtures.

Historical comparisons

Possible additions:

• compare two JSON reports without a service;
• show changes in utilization, underfill, and slow attempts;
• support a baseline file in CI;
• keep thresholds behavioral rather than tied to unstable wall-clock bounds.

Event-loop responsiveness

The original brief proposed an asyncio watchdog that periodically measures loop lag. A responsible implementation would need to answer:

• which loop is authoritative when plugins create multiple loops;
• how watchdog lifecycle follows pytest fixtures and workers;
• how measurement overhead is bounded;
• whether a stall can be attributed to a test without private plugin state;
• how external waiting differs from blocking work.

Until those questions have robust answers, poolwatch_blocking remains a documentation marker and reports do not claim loop-starvation detection.

User-defined phases

A future fixture or context manager could label work such as:

async with poolwatch.phase("submit"):
    job_id = await submit()

async with poolwatch.phase("external-wait"):
    result = await wait(job_id)

This could distinguish submission, remote waiting, and validation while keeping the test interval intact. It requires a stable cross-plugin context model before being added.

Safe synchronous offload

A later helper might run blocking validation in a thread and report queue and execution time. This is intentionally separate from observation and is not a v0.1 responsibility.

Non-goals

PoolWatch is not intended to become:

• a complete pytest runner;
• a replacement scheduler;
• a fixture-lifecycle implementation;
• an automatic thread-offloading system;
• a hosted dashboard or mandatory server;
• an AI-generated diagnosis service;
• an external cloud-job scheduler.

How priorities are chosen

A proposed feature is strongest when it includes:

1. a real surprising concurrency trace;
2. a minimal deterministic reproduction;
3. a public signal PoolWatch can measure;
4. a clear distinction from normal behavior;
5. tests that assert invariants rather than invented benchmark numbers.

Open proposals at: https://github.com/Butterski/pytest-poolwatch/issues