Python test coverage

Ask your coding agent to set up Supercov in your project:

Install supercov-cli in this project's Python environment. Read supercov docs
and run our existing tests with the project's interpreter. Follow
supercov docs assertion-agent to build and validate the assertion map.
Show the coverage report and any measurement limits. Don't change
application code or tests.

Run it yourself

You’ll need CPython 3.12 or newer. Activate your project’s virtual environment with its test dependencies installed.

The PyPI package is called supercov-cli; its command is supercov. Install it in your active virtual environment:

python -m pip install supercov-cli
supercov --version

With uv, you can use uv pip install supercov-cli instead. Neither option needs Node.js. Keep the environment active when running the commands below.

Run your tests

From your project root, wrap the command that runs your suite:

supercov -- python -m pytest

For a project managed by uv, or a unittest suite, use its normal command instead:

supercov -- uv run pytest
supercov -- python -m unittest discover

Supercov measures Python in your project directory. You don’t need a coverage configuration file. It can track separate pytest-xdist workers and test retries.

Read the report:

supercov runs latest
supercov runs latest gaps --limit 5

If you prefer not to install Supercov in the project, use uvx with an explicit path to the project’s interpreter, or let uv run select its environment:

uvx --from supercov-cli supercov -- .venv/bin/python -m pytest
uvx --from supercov-cli supercov -- uv run pytest

Replace .venv/bin/python if your environment is elsewhere. Avoid plain python -m pytest after uvx: uvx puts its own environment first on PATH, and that interpreter may not have your project’s dependencies.

Try a small example

Download the examples, extract them, and open supercov-examples/python. This example uses unittest from the standard library, so you don’t need to install a test framework.

Its src/session.py file contains:

def checkout(signed_in, expired, price, quantity):
    if signed_in and not expired:
        total = price * quantity
        return {"status": "confirmed", "total": total}
    return {"status": "denied", "total": 0}

The tests check a valid order and a signed-out visitor. From the example folder:

supercov -- python -m unittest discover -s tests
supercov runs latest

This is the coverage section recorded with Supercov 0.0.48:

Coverage
  Lines      100.00% (5/5)
  Branches   100.00% (6/6)
  MC/DC      50.00% (1/2)

To find the missing case:

supercov runs latest decision src/session.py:2

The report includes:

signed_in and not expired
C1 covered: signed_in
C2 MISSING: not expired

No test checks a signed-in customer whose session has expired. Adding that case raises MC/DC to 100% in the recorded run. See MC/DC for why both branches can be covered while this case is missing.

Check what the tests assert

These tests check the status, not the total. Adding self.assertEqual(order["total"], 50) would check the calculation for this input.

The setup prompt asks your agent to map each assertion to the code it checks. Supercov checks the map against execution and passing assertions in the same test. An unmapped statement needs review; it isn’t automatically a missing test. See Assertion coverage.

Python-specific limits

Python started with -I, -E or -S skips Supercov’s startup hook and isn’t measured. Code compiled from strings at runtime isn’t included. unittest support is serial and in-process. See runner support for details.

Already using coverage.py? See how the reports differ. supercov docs coverage-model prints the guide for your installed version.