Installation¶
Install vfy in your project to run tests, measure coverage, and run only the tests affected by your changes.
vfy is Alpha and available on PyPI with prebuilt wheels for supported platforms. You need CPython 3.12+ and uv.
Installing a wheel does not require Git, Rust, or a C compiler. Affected-test selection uses Git to compare edits with a passing baseline.
vfy 0.0.1 ships wheels for Linux x86_64 and aarch64 (glibc and musl), and macOS x86_64 and arm64.
vfy test and vfy mutate run tests with vfy's native engine by default,
without installed pytest. Independent mutation testing requires Linux. For
the optional --engine=pytest-native route, install vfy[pytest]. On that route,
pytest collects the tests and vfy runs them. See Compatibility for supported versions,
plug-ins, and conftest.py hooks.
Install from PyPI¶
From your project directory, next to pyproject.toml, run:
uv add --dev vfy
This adds vfy to your test environment and records the resolved version in
uv.lock. Commit the dependency and lockfile changes to keep installs reproducible.
All examples use uv run to run tools from that environment.
If you use pip in an existing virtual environment instead:
python -m pip install vfy
Pin the vfy version in your requirements for repeatable installs. With pip,
omit uv run from the documentation commands.
Verify the installation¶
uv run vfy --version
uv run vfy diagnostics
Example output:
vfy 0.0.1
vfy 0.0.1 independent diagnostics
Python 3.13.9 (cpython, linux)
pytest: available
Independent runtime: available
vfy configuration: valid
...
vfy diagnostics reports your Python runtime, whether pytest is installed, and
whether vfy can read your configuration. The versions and paths in the output
are examples.
Run tests with coverage¶
On Linux or macOS, check your suite's compatibility, then run the full suite from your project root:
uv run vfy test --all --cov=src
Replace src with your source directory. vfy runs your tests, prints a coverage
report, and writes .coverage. See running tests for
selectors, workers, and report options. See test execution and pytest compatibility for engine
options and the optional coverage plug-in for pytest.
Try affected-test selection¶
Affected-test selection runs only the tests that reach your uncommitted edits.
It works with the default native engine on unfiltered safe coverage runs.
Create a passing baseline on a
clean Git commit; the selection guide explains which edits select a subset and
when to run the full suite.
Try the example project¶
The tutorials set up a small standalone project and install vfy from PyPI:
- Run affected tests: edit a function, run one of two tests, retain whole-project coverage, and look up the test for a line.
- Measure coverage with vfy: find a missing branch, add its test, and export reports on Linux or macOS.
For the optional pytest coverage integration, follow pytest setup.
Remove vfy¶
If you saved activation flags, remove -p vfy.pytest_plugin and
-p no:pytest_cov from pytest addopts, PYTEST_ADDOPTS, and CI commands first.
Also remove -p vfy.pytest_reporting if you enabled the optional reporter.
Otherwise pytest tries to import the removed plug-in and fails before collection.
Restore your pytest-cov dependency and original coverage command if you used them.
Optionally run uv run vfy cache clean before uninstalling to remove saved
selection data from .vfy/. This leaves the root .coverage file intact.
Then run uv remove --dev vfy, or python -m pip uninstall vfy for a pip
installation. Run your usual pytest command to check that the original setup works.
Install from source¶
For contributor work or an explicit source build, you need Git, Rust 1.95+, and a C compiler: Xcode Command Line Tools on macOS or your Linux distribution's build tools. Source builds can take several minutes. Follow the development setup in a vfy checkout, then build a wheel:
uv run maturin build --release --locked --out dist
Install that wheel in a matching platform's project environment:
uv add --dev "/path/to/vfy/dist/<wheel-filename>.whl"
Replace the path and filename with the built wheel. The receiving machine needs a supported CPython version and platform, but no Rust toolchain.