Development

Development

Clone and synchronize

git clone https://github.com/Butterski/pytest-poolwatch.git
cd pytest-poolwatch
uv sync --locked --dev

The default development environment includes pytest-asyncio, pytest-xdist, coverage, Ruff, and ty. The optional demo group pins a pre-fix pytest-asyncio-cooperative release and should not be mixed into ordinary xdist testing.

Quality checks

uv run ruff check .
uv run ruff format --check .
uv run ty check

Tests and coverage

uv run coverage erase
uv run coverage run -m pytest
uv run coverage combine
uv run coverage report

Coverage includes branches and subprocesses. The configured minimum is 90%.

The test layers are:

• analysis tests for timelines, drain, thresholds, and underfill;
• collector tests for phases, outcomes, retries, markers, and fallbacks;
• target tests for scheduler-capacity precedence;
• renderer tests for JSON, escaping, atomic writes, and terminal guidance;
• subprocess integration tests for real pytest registration and xdist reports.

Build distributions

uv build

This creates a pure-Python wheel and source distribution in dist/.

Check metadata before release:

uvx --from twine twine check dist/*

The wheel must contain:

• pytest_poolwatch package modules;
• py.typed;
• pytest entry-point metadata;
• MIT license metadata.

Run a local smoke test

Create a fresh environment, install the built wheel, and check plugin discovery:

uv venv .smoke-venv
uv pip install --python .smoke-venv dist/pytest_poolwatch-*.whl
.smoke-venv/bin/python -m pytest --help

On Windows, use .smoke-venv\Scripts\python.exe.

Examples

The optional regression dependency is installed only when requested:

uv sync --locked --no-dev --group demo

See Examples for pinned before/after commands. Do not run cooperative and xdist schedulers together.

Coding principles

• Prefer public pytest hooks over scheduler internals.
• Preserve pytest's original execution and exit status.
• Keep collection, analysis, and rendering separate.
• Diagnose only what the available evidence supports.
• Treat exact timing as observational unless a deterministic test establishes an invariant.
• Keep JSON changes backward compatible within schema version 1.

Submitting a change

1. Add or update a focused test.
2. Run lint, formatting, type checks, tests, and coverage.
3. Update the README or Wiki for user-visible behavior.
4. Update CHANGELOG.md under Unreleased.
5. Open a pull request explaining the observed problem and evidence.

Repository CI

The quality job runs on Python 3.11, 3.12, 3.13, and 3.14. Separate jobs run the PR #86 regression and the 800-job cloud simulation on pinned scheduler versions.

The publication workflow is separate and runs only when a GitHub Release is published. See Release Guide.