Skip to main content
Version: MVP

Coverage Reports

2 min readFor contributorsUpdated 2026-05-24

What ships with a release

Release tags generate HTML coverage, a coverage.xml artifact, and generated badge artifacts so contributors can inspect the tested surface without running the full suite locally. The README uses a static Shields badge for the latest release-prep coverage value so it renders before the release Pages workflow has published new artifacts.

Published Report​

The release coverage workflow runs on tag pushes and manual dispatch. It runs the pytest suite with pytest-cov, writes terminal, HTML, XML, and badge endpoint reports, uploads htmlcov/ as the craik-coverage workflow artifact, and attaches coverage.xml to the matching GitHub Release.

Coverage does not deploy to GitHub Pages. The craik.eidetic-labs.com Pages target is reserved for the product landing page built from site/.

.github/workflows/pages.yml deploys site/
.github/workflows/coverage.yml uploads htmlcov/ as an artifact only

Local Equivalent​

Run the same coverage command locally before release prep:

uv run pytest --cov=craik --cov-report=term --cov-report=html --cov-report=xml

The default local threshold is configured in pyproject.toml.

Coverage Threshold​

The release workflow enforces a minimum overall coverage of 80%. If a release-tag push drops total coverage below this threshold, the coverage workflow fails before uploading the artifact or attaching coverage.xml to the GitHub Release.

The threshold is set below the current measured full-suite coverage to allow normal variance from feature work. Raise it only after main has stayed green at the higher threshold. Lower it only with explicit maintainer rationale and a follow-up issue to recover the floor.

Reading the Report​

Use the report to answer focused review questions:

  • Which new code paths have no direct tests?
  • Which changed files rely only on broad integration coverage?
  • Which branches need a negative or failure-path test before release?

Coverage is a guardrail, not proof of correctness. Security, migration, provider, and TUI behavior still need targeted tests that exercise the user workflow and failure mode.