vfy¶
A Python test runner and coverage tool, built in Rust.
vfy runs your Python tests and measures their coverage:
- Run pytest-style suites.
vfy testcollects and runs tests with its own engine by default. You can use it without installing pytest. Check compatibility for supported tests and plug-ins. - Select affected tests. Rerun tests that reached the code you changed and reuse coverage from the rest.
- Measure coverage. See which lines and branches your tests run, and which they miss.
- Find weak assertions. Change an operator such as
>=to>in memory and check whether your tests catch the difference. - Find missing test cases. See which conditions inside an
andororexpression your tests never exercise, even with 100% line coverage.
Get started¶
vfy is Alpha. On Linux or macOS with CPython 3.12+ and uv, install it and run your tests:
uv add --dev vfy
uv run vfy test
Check compatibility for supported tests and plug-ins and installation for platform requirements. For a complete example with source files and expected output, follow the coverage tutorial.
Collect and report coverage¶
Measure your application's lines and branches:
uv run vfy test --cov=src --cov-branch --cov-report=term-missing
Replace src with your source directory. vfy prints missing lines and branches
and saves .coverage. Use the
coverage guide to generate HTML, JSON, XML, and LCOV
reports from that saved data without rerunning tests.
Run affected tests¶
First check your suite's compatibility.
Add .vfy/ to .gitignore and commit your setup. From a clean Git checkout,
run the full suite once:
uv run vfy test --all --cov=src
vfy saves the passing run and records which tests reached which code. Edit a function, leave the change uncommitted, then run:
uv run vfy test --cov=src
vfy picks tests using the earlier run's coverage and imports. For example, in the two-test tutorial, changing a bounds-checking function reruns its test and skips an unrelated formatting test.
Replace src with your source directory and keep coverage and worker options
the same between runs. Missing saved data, test or fixture changes, and changes
vfy cannot map to tests cause a full run. Use --all for full-suite CI checks
and changes to external services, environment variables, or shared test state.
How selection works.
Check what your tests prove¶
A line can run without its result ever being checked. vfy includes two ways to look beyond a line-coverage percentage:
- Mutation testing: vfy makes a small change in memory,
such as replacing
>=with>, and runs the relevant tests. If they still pass, review whether an assertion missed a bug or the change is equivalent. - Decision coverage: vfy records the conditions inside
expressions such as
x >= 0 and x < 10, so you can find inputs your tests have not exercised even when both branches ran.
See the guides for their requirements and limits.
FAQ¶
How do you pronounce vfy?¶
Say “verify.” Write it vfy, in lowercase.
Can I use my existing pytest suite?¶
Yes. vfy supports pytest-style fixtures, parametrization, and assertions. Check compatibility for the hooks and plug-ins your suite uses.
Does test selection replace full-suite CI?¶
No. Keep full-suite CI checks. Use --all for changes to external services,
environment variables, or shared test state. Selection rules.
Reference and help¶
Use the CLI reference for commands and options, the configuration reference for project settings, and the CI guide for full-suite checks. For help, see troubleshooting and the FAQ.