suite-doctor

A pytest-integrated health checkup tool. Runs your existing test suite via pytest and reports on its health — not another test framework, a wrapper around the one you already use.

Status

Shipped on PyPI. Core pipeline, flaky detection, coverage, config support, and JSON output all working.

Why

pytest tells you pass/fail. suite-doctor tells you:

• Slowest tests, sorted
• Failures with short message + full traceback (--verbose)
• Flaky tests — re-runs failures N times, flags inconsistent ones
• Coverage summary — % covered, worst-covered files (--coverage)
• Skipped/xfail counts
• Clean, colorized CLI output (via rich) instead of pytest's default verbose dump
• Machine-readable output for scripts/CI (--json)

How it works

Shells out to pytest --json-report (via pytest-json-report), parses the JSON, formats a summary. No pytest internals, no plugin hooks — just wraps the CLI you already run.

Requirements

• Python 3.11+
• pytest
• pytest-json-report
• pytest-cov
• rich

Install

pip install suite-doctor

Usage

suite-doctor <path-to-project>

Example:

suite-doctor ./my-project

Flags

• --top, -t — number of slowest tests to show (default: 5)
• --rerun — number of reruns for flaky detection (default: 3)
• --verbose, -v — show full tracebacks for failures
• --coverage, -c — show coverage summary
• --json — output results as JSON

Config file

Set defaults in your project's pyproject.toml:

[tool.suite-doctor]
top = 10
rerun = 5
coverage = true

CLI flags always override config file values.

Roadmap

• Subprocess runner
• Report parsing (summary/slowest/failures)
• Flaky test detection
• Coverage integration
• Config file support
• --json output mode
• Published to PyPI
• Exit code reflects pass/fail (CI use)
• Tests for suite-doctor itself