Run affected tests¶
Run two tests, edit one function, then run only the test that reached it. vfy combines the selected test's new coverage with saved coverage for the skipped test. You inspect that report and find which test reached a source line.
The tutorial needs Linux or macOS, CPython 3.12+, uv, and Git for the
selection baseline. Install vfy from PyPI; see Installation.
Set up the example¶
Follow Set up the example. All commands below run from that project's root.
If you already completed the coverage tutorial, create a fresh example using a
different directory name in its uv init command. Start with the original two
tests so the negative-input branch remains uncovered.
The project has two source files and two tests. One asserts clamp_low(5) == 5;
the other asserts format_count(42) == "42" without calling clamp_low.
The value < 0 branch in clamp_low has no test yet. The configuration adds
src to pytest's import path and enables branch coverage.
Create a clean Git baseline¶
A passing baseline is a saved passing full run on a clean Git commit. vfy uses it to learn which tests reach which lines.
In the example directory, initialize a separate Git repository and commit the
starting project. This keeps the tutorial baseline scoped to the example.
Configure your Git name and email first if you have not. The included
.gitignore already ignores .vfy/, where vfy keeps its baseline.
git init
git add .
git commit -m "Start coverage example"
uv run vfy test --engine=native --all -j 1 --cov=src --cov-branch --cov-report= -v
Both tests pass, and vfy saves the passing baseline in .vfy/. The
negative-input branch is still untested: a baseline requires passing tests,
not full coverage.
Edit bounds.py¶
Replace src/bounds.py with this equivalent version. Leave the change
uncommitted so vfy can compare it with the baseline commit:
from __future__ import annotations
def clamp_low(value: int) -> int:
if value < 0:
return 0
return int(value)
Run the tests:
uv run vfy test --engine=native -j 1 --cov=src --cov-branch --cov-report= -v
vfy prints a summary on stderr. The numbers and paths are illustrative:
Changed code: /path/to/vfy-coverage-example/src/bounds.py
Affected code: 1 functions, 0 branches
Selected 1 / 2 tests (after collection)
Tests outside the selection were skipped; `vfy test --all` runs everything
Estimated selected suite: 0.00s
Estimated full suite: 0.00s
...test output...
Reused 1 tests; complete coverage reconstructed from passing baseline 1a2b3c4d
vfy selected 1 of 2 tests: tests/test_bounds.py::test_positive_value.
It reused the formatting test's baseline coverage and exited with status 0.
Why only one test: your edit changed the body of clamp_low, and an edit
inside a function body selects only the tests that ran that function in the
baseline. test_positive_value calls clamp_low. test_format_count never
does, so vfy skipped it. Edits elsewhere in a Python file select more tests;
the selection rules list
every case.
Report the combined coverage¶
uv run vfy coverage report --show-missing
The report combines the selected test's new coverage with the formatting test's baseline. It covers both files and totals 80%. The negative-input branch is still untested.
Find the test for a line¶
vfy test --engine=native records per-test coverage automatically.
vfy explain reads that saved coverage and lists the tests that reached a line,
without running them. Here, line 7 still belongs to the edited function:
$ uv run vfy explain src/bounds.py:7
Tests reaching src/bounds.py:7: 1
Estimated selected suite: 0.00s
Estimated full suite: 0.00s
tests/test_bounds.py::test_positive_value 0.001s
This command reads the last coverage recording; it does not explain why tests were selected. Recollect after edits so paths and line numbers stay current. Semantic coverage can add pairs of recorded inputs showing how individual conditions affect a result.
Add --json for the same data as JSON:
uv run vfy explain src/bounds.py:7 --json
The output has a location, a selection object, semantic_evidence, and a
tests list (abridged; durations vary between runs):
{
"location": "src/bounds.py:7",
"tests": [
{"duration_ms": 0.13, "nodeid": "tests/test_bounds.py::test_positive_value"}
]
}
Observe the full-run fallback¶
Clear vfy's disposable cache and run again:
uv run vfy cache clean
uv run vfy test --engine=native -j 1 --cov=src --cov-branch --cov-report= -v
With no passing baseline, vfy runs both tests and prints Note: no passing
baseline exists yet. Both tests pass.
To make this edit the new baseline, commit it and run the full suite:
git add src/bounds.py
git commit -m "Convert the bounded value explicitly"
uv run vfy test --engine=native --all -j 1 --cov=src --cov-branch --cov-report= -v
Use this on your own suite¶
Check compatibility, ignore .vfy/, and
commit your setup changes. On a clean checkout, run
uv run vfy test --engine=native --all --cov=src; after each uncommitted edit, run
uv run vfy test --engine=native --cov=src. Replace src with your source directory and
keep coverage and worker options consistent.
Selection cannot see external services, clocks, environment changes, or state
shared between tests. Use --all for those changes and for full-suite CI checks.
Read the selection rules for details.
Next, measure coverage and close the missing branch, run in parallel, or use vfy in CI.