This document describes the testing infrastructure in the uv codebase, including the test organization, snapshot testing approach, scenario generation, and test utilities. It covers integration tests, unit tests, and specialized environment testing (Conda, Nushell, and System Python). It also details the agents/ directory containing AI automation tooling for issue triage and bug reproduction.
For information about the build system and CI/CD pipeline, see Build System and Release Pipeline.
The test suite is organized into several key components to ensure coverage from unit-level logic to end-to-end CLI behavior.
| Component | Location | Purpose |
|---|---|---|
| Integration Tests | crates/uv/tests/ | End-to-end CLI command testing (e.g., pip_install/, lock/, sync/) [crates/uv/tests/pip_install/pip_install.rs:104-106] |
| Test Utilities | crates/uv-test/src/lib.rs | Shared test fixtures, TestContext, and snapshot filters [.github/workflows/sync-python-releases.yml:53-53] |
| Scenario Tests | crates/uv/tests/lock_scenarios/ | Generated tests for complex dependency resolution edge cases [crates/uv/tests/lock_scenarios/lock_conflict.rs:1-10] |
| Unit Tests | Within each crate | Component-level testing (e.g., uv-resolver, uv-python) |
| Ecosystem Tests | test/ecosystem/ | Testing against real-world projects like transformers and warehouse [.github/workflows/ci.yml:129-134] |
Sources: [.github/workflows/test.yml:28-31], [.github/workflows/test.yml:108-115], [crates/uv/tests/pip_install/pip_install.rs:104-106].
The TestContext struct (defined in uv-test) is the central entity for integration testing. It manages isolated temporary directories, provides a handle to the uv binary, and maintains a set of filters for snapshot normalization.
Sources: [crates/uv/tests/pip_install/pip_install.rs:37-40], [crates/uv/tests/pip_install/pip_install.rs:106-107].
Each test instance creates a unique environment to prevent interference:
temp_dir: The current working directory for the test, often containing pyproject.toml or requirements.txt [crates/uv/tests/pip_install/pip_install.rs:107-108].cache_dir: An isolated global cache for the specific test run.venv: A virtual environment path, typically .venv within temp_dir.uv relies heavily on insta for snapshot testing. This allows developers to verify CLI output (stdout/stderr) and file contents (like uv.lock) against a baseline.
The uv_snapshot! macro is a wrapper around insta::assert_snapshot! that applies standard filters to the command output before comparison [crates/uv/tests/pip_install/pip_install.rs:19-19], [crates/uv/tests/pip_install/pip_install.rs:109-112].
To ensure snapshots pass on Linux, macOS, and Windows, TestContext applies several regex-based filters:
[TIME] [crates/uv/tests/pip_install/pip_install.rs:141-141].[TEMP_DIR] [crates/uv/tests/pip_install/pip_install.rs:228-228].Sources: [crates/uv/tests/pip_install/pip_install.rs:37-40], [.github/workflows/test.yml:105-106].
The agents/ directory contains configuration and logic for AI-driven development automation, primarily using Codex/OpenAI. These tools assist in issue triage, bug reproduction, and workflow diagnosis.
Key Agent Components:
agents/schemas/issue-triage-bug.json and .github/workflows/issue-triage.yml to automatically label and categorize incoming bugs.agents/prompts/reproduce-bug.md and agents/prompts/create-bug-test.md to attempt to generate a minimal reproducible test case from a bug report [agents/prompts/reproduce-bug.md:1-10], [agents/prompts/create-bug-test.md:1-10]..codex/skills/load-github-action-thread/ allow agents to analyze CI failure logs to diagnose regressions [.codex/skills/load-github-action-thread/SKILL.md:1-5].Sources: [.github/workflows/issue-triage.yml:1-10], [.github/workflows/reproduce-bug.yml:1-10], [agents/codex/config.toml:1-5].
The testing infrastructure includes specialized CI jobs to verify uv across different shells, managers, and operating systems.
The integration suite tests uv against various system-level components:
activate.nu script behavior by creating a venv and activating it within a nu shell environment using overlay use [.github/workflows/test-integration.yml:19-64].macosx_10_16 vs macosx_11_0 causing uv to consider wheels incompatible) [.github/workflows/test-integration.yml:66-136].uv's interaction with externally managed system installations across Debian, Fedora, and Ubuntu. It tests uv venv behavior with system-only preferences [.github/workflows/test-integration.yml:137-183].cargo bloat [.github/workflows/test-windows-trampolines.yml:35-56], [.github/workflows/test-windows-trampolines.yml:102-113].The project uses cargo-nextest for test execution, with specific profiles for CI and local development:
UV_HTTP_RETRIES: 5 to reduce flakes in CI due to network issues [.github/workflows/test.yml:98-98].btrfs (for CoW/reflink), tmpfs, and minix (for hardlink limits) to ensure robust file handling [.github/workflows/test.yml:67-88].Performance is tracked using codspeed and uv-bench.
pip compile and wheel installation on aarch64 linux runners [.github/workflows/bench.yml:63-96].cargo codspeed run for stable performance tracking independent of runner noise [.github/workflows/bench.yml:97-137].Static analysis and schema checks are performed to ensure code quality:
uv check --script with UV_PREVIEW_FEATURES: check-command,workspace-list-scripts [.github/workflows/check-lint.yml:48-60].uv.schema.json against project configurations [.github/workflows/check-lint.yml:89-96].Sources: [.github/workflows/test.yml:28-115], [.github/workflows/test-integration.yml:1-183], [.github/workflows/bench.yml:1-137], [.github/workflows/test-windows-trampolines.yml:1-162], [.github/workflows/check-lint.yml:48-60].
Refresh this wiki