Testing

Running the suite

$ python -m pytest

The suite lives in tests/, one module per source module:

Test module

Covers

test_cli.py

parsing, --dry-run, --list-pythons, exit codes

test_config_spec.py

option specs and value coercion

test_config_loader.py

TOML/INI/env loading, discovery order, precedence

test_discovery.py

spec grammar, discover() paths

test_discovery_providers.py

PATH/registry/launcher/uv/pyenv providers

test_discovery_python_info.py

probing, caching, spec matching

test_create_context.py

the CreatorContext contract

test_create_creator.py

Windows/POSIX creators, pyvenv.cfg, clear/upgrade

test_create_activators.py

every template, quoting, placeholder leaks

test_seed.py

seeder command construction (subprocesses mocked)

test_session_options.py

Options validation and derived properties

test_create_venv.py

end-to-end creation, isolation checks

test_errors.py, test_report.py

exception text, leveled output

test_util_lock.py, test_util_path.py, test_util_process.py

utilities

test_package.py

packaging metadata and imports

Properties the suite guarantees

  • Unit tests never touch the network and never spawn pip. Seeder tests intercept run_cmd; discovery tests use the running interpreter or fakes.

  • Integration tests create real environments under tmp_path and then execute the new interpreter to verify sys.prefix isolation and pip presence. These are the slow tests; everything else is milliseconds.

  • Platform-specific tests skip cleanly. POSIX symlink behavior is skipped on Windows and vice versa (pytest.mark / explicit guards), so the suite is green on every supported host.

  • No test depends on machine state. An autouse fixture points TN_VENV_CONFIG_FILE at an empty file and strips ambient TN_VENV_* variables, so a developer’s personal configuration can never leak into a test run.

Building this documentation

$ pip install -r docs/requirements.txt
$ sphinx-build -M html docs docs/_build          # POSIX
$ docs\make.bat html                              # Windows

The build uses Sphinx with MyST (Markdown), sphinx-design, the Read the Docs theme, and sphinx-copybutton. docs/conf.py reads the release from installed package metadata and falls back to tn_venv/version.py when the package is not installed, so the docs build from a bare checkout.

Coverage and hygiene

The suite passes with 315 tests on CPython 3.14/Windows at the time of writing. New features are expected to arrive with unit tests for logic and, where the feature crosses a process boundary, one integration test that runs the real thing.