This document describes the testing infrastructure in the uv codebase, including the test framework, snapshot testing approach, scenario generation, and test utilities. It covers integration tests, unit tests, scenario-based testing with packse, and the code generation pipeline that supports testing.
For information about the build system and CI/CD pipeline, see Build System and Release Pipeline. For Docker-related testing, see Docker Images and Distribution.
The test suite is organized into several key components:
| Component | Location | Purpose |
|---|---|---|
| Integration Tests | crates/uv/tests/it/ | End-to-end command testing |
| Test Utilities | crates/uv/tests/it/common/mod.rs | Shared test fixtures and helpers |
| Scenario Tests | Generated from packse scenarios | Dependency resolution edge cases |
| Unit Tests | Within each crate | Component-level testing |
Sources: crates/uv/tests/it/common/mod.rs1-960 scripts/scenarios/generate.py1-363
The TestContext struct provides a comprehensive test fixture with isolated temporary directories, Python version management, and snapshot filtering.
Sources: crates/uv/tests/it/common/mod.rs90-115 crates/uv/tests/it/common/mod.rs117-884
Each test creates isolated directories to prevent interference:
The test context creates a .git directory at the root to isolate tests from the actual repository state, preventing git-based discovery from escaping the test sandbox.
Sources: crates/uv/tests/it/common/mod.rs610-650 crates/uv/tests/it/common/mod.rs616-619
The filter system enables deterministic snapshot tests across platforms by normalizing paths, versions, timestamps, and platform-specific output.
| Filter Type | Purpose | Example |
|---|---|---|
| Path normalization | Convert absolute paths to placeholders | /tmp/xyz → [TEMP_DIR] |
| Platform differences | Normalize Windows vs Unix paths | \ → /, .exe removal |
| Version filtering | Remove version numbers | Python 3.12.8 → Python 3.12.[X] |
| Timing/size | Remove non-deterministic data | 42ms → [TIME], 5.3MB → [SIZE] |
| Python executables | Normalize Python binary names | python3.12.exe → /[PYTHON] |
Sources: crates/uv/tests/it/common/mod.rs63-82 crates/uv/tests/it/common/mod.rs689-866
The TestContext provides numerous methods to add filters:
Sources: crates/uv/tests/it/common/mod.rs156-437
Tests can provision multiple Python versions for comprehensive testing.
Sources: crates/uv/tests/it/common/mod.rs668-687
Sources: crates/uv/tests/it/common/mod.rs670-687 scripts/scenarios/templates/compile.mustache24-41
Scenario tests are generated from packse scenarios, which define dependency resolution edge cases and expected outcomes.
Sources: scripts/scenarios/generate.py96-286
Each scenario template defines the test structure:
Sources: scripts/scenarios/templates/install.mustache1-82 scripts/scenarios/templates/compile.mustache1-107 scripts/scenarios/templates/lock.mustache1-98
Tests are categorized based on resolver options:
Sources: scripts/scenarios/generate.py179-195
The test suite uses insta for snapshot testing, combined with cargo nextest for parallel execution.
Sources: crates/uv/tests/it/common/mod.rs1000-1033
The uv_snapshot! macro combines filtering and assertion:
Sources: crates/uv/tests/it/common/mod.rs1000-1033
Several code generation tools support the testing infrastructure.
Sources: crates/uv-python/fetch-download-metadata.py1-650
This generation ensures that Python installations are properly patched to use generic compiler names (cc, c++, ar) instead of specific build-time paths, making installations relocatable.
Sources: crates/uv-dev/src/generate_sysconfig_mappings.rs30-175
Sources: crates/uv-dev/src/generate_all.rs1-38
The TestContext provides numerous helper methods for common test operations.
| Method | Purpose | Returns |
|---|---|---|
command() | Generic uv command | Command |
pip_install() | pip install command | Command |
pip_sync() | pip sync command | Command |
pip_compile() | pip compile command | Command |
run() | uv run command | Command |
lock() | uv lock command | Command |
sync() | uv sync command | Command |
venv() | venv creation command | Command |
python_install() | python install command | Command |
python_uninstall() | python uninstall command | Command |
python_upgrade() | python upgrade command | Command |
Sources: crates/uv/tests/it/common/mod.rs886-960
Sources: crates/uv/tests/it/common/mod.rs936-960
The testing infrastructure integrates with the CI/CD pipeline for multi-platform testing.
Tests are gated behind feature flags for selective execution:
| Feature Flag | Purpose | Example |
|---|---|---|
pypi | Tests requiring package index access | Dependency resolution tests |
python | Tests requiring Python installation | Python version tests |
python-patch | Tests requiring specific patch versions | Version-specific behavior |
git | Tests requiring git functionality | Git dependency tests |
Sources: scripts/scenarios/templates/install.mustache6 crates/uv/tests/it/python_install.rs1
Sources: High-level diagram 8, scripts/scenarios/generate.py254-283
Tests use cargo nextest for parallel execution with test isolation:
Sources: scripts/scenarios/generate.py257-278
The testing infrastructure provides:
insta with extensive filteringThe architecture emphasizes isolation, reproducibility, and maintainability, enabling comprehensive testing across platforms and Python versions while minimizing manual test maintenance through code generation.
Refresh this wiki