# Python test coverage

> Set up Supercov with your agent, or run it yourself with pytest or unittest.

Web page: https://supercov.com/docs/python
All Supercov pages for agents: https://supercov.com/llms.txt · Full text: https://supercov.com/llms-full.txt

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

```text supercov-prompt
Install supercov-cli in this project's Python environment. Read supercov
docs and run our existing tests with the project's interpreter. Show the
coverage report and any measurement limits. Don't change application code or
tests.
```

## Run it yourself

You'll need CPython 3.9 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:

```sh
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:

```sh
supercov -- python -m pytest
```

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

```sh
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:

```sh
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:

```sh
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](https://supercov.com/downloads/supercov-language-examples.zip), 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:

```python
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:

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

This is the coverage section recorded with Supercov 2.0.0:

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

To find the missing case:

```sh
supercov runs latest decision src/session.py:2
```

The report includes:

```text
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](https://supercov.com/downloads/coverage-guide-recordings.json).
See [MC/DC](https://supercov.com/docs/mcdc?language=python) 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.

Supercov can ask [Jev](https://typesafe.ai) whether each test would fail if a
statement it ran changed. `runs latest assertions assess` saves the answers
(it needs `TYPESAFE_API_KEY`), and `runs latest assertions` then lists the
statements no test checks, file by file. A statement that is not asserted
runs in some test, but nothing that test checks depends on it. See
[Assertion coverage](https://supercov.com/docs/assertions?language=python).

## 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](https://supercov.com/docs/supported-suites?language=python#python) for details.

Already using coverage.py? See [how the reports differ](https://supercov.com/compare/python-code-coverage.md).
`supercov docs coverage-model` prints the guide for your installed version.