Configuration

Configuration

PoolWatch accepts command-line options and pytest configuration. Command-line values take precedence.

Command-line options

Option	Value	Behavior
--poolwatch	flag	Enable collection and the terminal summary.
--poolwatch-target=N	positive integer	Set expected active-test capacity.
--poolwatch-json=PATH	path	Write JSON and enable PoolWatch.
--poolwatch-html=PATH	path	Write HTML and enable PoolWatch.
--poolwatch-underfill-threshold=SECONDS	non-negative float	Filter shorter underfill windows; default 0.1.

Example:

pytest tests/integration \
  --poolwatch \
  --poolwatch-target=24 \
  --poolwatch-underfill-threshold=0.25 \
  --poolwatch-json=.poolwatch/integration.json \
  --poolwatch-html=.poolwatch/integration.html

pyproject.toml

[tool.pytest.ini_options]
poolwatch = true
poolwatch_target = 24
poolwatch_json = ".poolwatch/integration.json"
poolwatch_html = ".poolwatch/integration.html"
poolwatch_underfill_threshold = 0.25

The same names can be used in pytest.ini:

[pytest]
poolwatch = true
poolwatch_target = 24
poolwatch_json = .poolwatch/integration.json
poolwatch_html = .poolwatch/integration.html
poolwatch_underfill_threshold = 0.25

Enablement rules

PoolWatch is enabled when any of these conditions is true:

1. --poolwatch is present;
2. poolwatch = true is configured;
3. a JSON output path is configured;
4. an HTML output path is configured.

Setting a target alone does not enable collection.

Target selection

Target precedence is:

1. --poolwatch-target=N;
2. poolwatch_target from pytest configuration;
3. a capacity detected from the active supported scheduler;
4. the observed peak as a non-diagnostic fallback where appropriate.

Explicit targets are useful for custom schedulers and for making CI behavior stable across machines.

Invalid explicit values fail fast with a pytest usage error. Targets must be greater than zero.

Underfill threshold

Small timing gaps are common around report boundaries and usually do not deserve attention. The default threshold ignores a contiguous underfill window shorter than 100 ms:

pytest --poolwatch --poolwatch-underfill-threshold=0.1

Use zero when developing a deterministic scheduler regression:

pytest --poolwatch --poolwatch-underfill-threshold=0

Use a larger threshold for noisy, long-running integration suites.

The threshold filters windows by duration; it does not change utilization or idle slot-seconds.

Output paths

Relative paths are resolved against pytest's root directory, not necessarily the current shell directory. Absolute paths are preserved.

If a report cannot be written, PoolWatch emits a PytestWarning rather than changing the test session's original exit status.

Markers

poolwatch_ignore

Excludes a test from collected counts, intervals, queue state, and summary metrics. The test itself still runs.

poolwatch_blocking

Documents that a test is expected to perform blocking work. It is registered so strict marker configurations accept it, but v0.1 does not yet use it for loop stall measurement or attribution.

Recommended CI configuration

[tool.pytest.ini_options]
poolwatch = true
poolwatch_target = 16
poolwatch_json = ".poolwatch/ci.json"
poolwatch_html = ".poolwatch/ci.html"
poolwatch_underfill_threshold = 0.25

Upload both report files as CI artifacts, retain JSON for comparisons, and treat timing values as observations unless the workload is intentionally deterministic.