testrisk

Find the code most likely to need better tests. testrisk reads coverage.py data, maps uncovered lines onto functions, and ranks them by test risk — not another coverage percentage.

Why testrisk?

• Rank gaps, do not just list them — uncovered branches, cyclomatic-ish complexity, git-changed lines, and missing tests all feed one score
• Human by default, JSON when you need it — --prompt turns the same evidence into a concise agent task
• Optional changed-line gate — --fail-under-changed 95 for CI; the default command still just advises
• Small install — one runtime dependency: coverage (see pyproject.toml)

testrisk 1.0.0

Coverage   91.7%
Branch     84.2%

Highest-value test gaps

  1. demo/services.py::ServiceManager.start
     Missing: 15-18
     Branches: 2 uncovered
     Complexity: 3
     Risk: HIGH

Changed code
  94.1% covered
  2 uncovered executable lines

Suggested next target:
  tests/test_services.py

Installation

uvx (recommended — zero install)

cd /path/to/your/repo
uvx testrisk

Persistent install on your PATH:

uv tool install testrisk
testrisk --doctor

via pipx (isolated CLI)

pipx install testrisk

via pip

pip install testrisk

If testrisk is not on your PATH

python -m testrisk --version
python -m testrisk --doctor

from source

git clone https://github.com/karlhillx/testrisk.git
cd testrisk
uv sync
uv run testrisk --version
uv run python -m testrisk --version

Quick start

Generate coverage first (pytest-cov or coverage.py), then rank:

pytest --cov --cov-report=json
testrisk

testrisk looks for coverage.json, then coverage.xml, then .coverage, walking up from . to the nearest pyproject.toml / .git when --repo is omitted.

testrisk --changed                 # only gaps on git-changed lines
testrisk --top 10                  # default
testrisk --file src/foo.py         # one file (repeatable)
testrisk --json                    # machine-readable report
testrisk --prompt                  # evidence-based agent task
testrisk --fail-under-changed 95   # exit 1 if changed-line coverage is low
testrisk --doctor                  # coverage file, git, and Python

--quiet prints only the suggested next test file.

--prompt

Write focused unit tests for these uncovered behaviors.

Do not modify production code unless required to expose a testable seam.

Target:
src/foo.py::parse_config

Uncovered:
44-48, 57

Untested branches:
line 46: false branch
line 57: exception/exit branch

Complexity: 6
Risk: MEDIUM

Existing tests:
tests/test_foo.py

How ranking works

Each function or method with uncovered statements or branches gets a score:

Risk is HIGH / MEDIUM / LOW from that score plus a few hard rules (for example: five or more changed uncovered lines, or complexity ≥ 10 with two uncovered branches).

Related tests are existing test_*.py / *_test.py files that mention the function or module stem. If none exist, the suggestion is tests/test_<stem>.py.

--base defaults to origin/main, then main, then origin/master, then master, then HEAD. Changed lines are git diff against the merge-base of that ref (plus your working tree).

Exit codes

Use as a library

testrisk ships type hints (py.typed) and a small public API:

from testrisk import GapError, analyze

try:
    report = analyze(".", changed_only=True, top=5)
except GapError as exc:
    raise SystemExit(exc) from exc

for gap in report.gaps:
    print(gap.qualname, gap.risk, gap.score)

analyze(...) returns a GapReport. Optional kwargs: coverage, changed_only, base, files, top. You can also pass an Options instance. Only names in testrisk.__all__ are public; import the CLI via python -m testrisk or the testrisk console script.

Requirements

• Python 3.12+ (requires-python in pyproject.toml)
• OS Linux, macOS, and Windows
• coverage 7.x (installed automatically with testrisk)
• git (optional; needed for --changed, the changed-code section, and --fail-under-changed)

Local development

uv sync
uv run pytest
uv run pytest --cov=testrisk --cov-report=xml tests/
uv run ruff check testrisk tests
uv run ty check

Environment variables

testrisk does not run your test suite. It only reads coverage artifacts, source files, and git diffs.

Troubleshooting

"No coverage data found"

Run tests with coverage and write a report in the repo root:

pytest --cov --cov-report=json
# or
coverage run -m pytest && coverage json

Then pass --coverage PATH if the file is not in the usual place.

Changed-code section is missing

The checkout is not a git repo, or git is not on PATH. --fail-under-changed needs git.

uvx: command not found

Install uv (curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv), then retry uvx testrisk.

License

MIT License - see LICENSE for details.

Contributing

See CONTRIBUTING.md. User-facing changes should be noted in CHANGELOG.md. Security reports: SECURITY.md.

Links

• PyPI
• GitHub Repository
• Issue Tracker