Struct TestContext 

pub struct TestContext {
    pub root: ChildPath,
    pub temp_dir: ChildPath,
    pub cache_dir: ChildPath,
    pub python_dir: ChildPath,
    pub home_dir: ChildPath,
    pub user_config_dir: ChildPath,
    pub bin_dir: ChildPath,
    pub venv: ChildPath,
    pub workspace_root: PathBuf,
    pub python_version: Option<PythonVersion>,
    pub python_versions: Vec<(PythonVersion, PathBuf)>,
    /* private fields */
}

Create a context for tests which simplifies shared behavior across tests.

• Set the current directory to a temporary directory (temp_dir).
• Set the cache dir to a different temporary directory (cache_dir).
• Set a cutoff for versions used in the resolution so the snapshots don’t change after a new release.
• Set the venv to a fresh .venv in temp_dir

Fields

root: ChildPath

temp_dir: ChildPath

cache_dir: ChildPath

python_dir: ChildPath

home_dir: ChildPath

user_config_dir: ChildPath

bin_dir: ChildPath

venv: ChildPath

workspace_root: PathBuf

python_version: Option<PythonVersion>

The Python version used for the virtual environment, if any.

python_versions: Vec<(PythonVersion, PathBuf)>

All the Python versions available during this test context.

Implementations

impl TestContext

pub fn new_with_bin(python_version: &str, uv_bin: PathBuf) -> Self

Create a new test context with a virtual environment and explicit uv binary path.

This is called by the test_context! macro.

pub fn with_exclude_newer(self, exclude_newer: &str) -> Self

Set the “exclude newer” timestamp for all commands in this context.

pub fn with_http_timeout(self, http_timeout: &str) -> Self

Set the “http timeout” for all commands in this context.

pub fn with_concurrent_installs(self, concurrent_installs: &str) -> Self

Set the “concurrent installs” for all commands in this context.

pub fn with_filtered_counts(self) -> Self

Add extra standard filtering for messages like “Resolved 10 packages” which can differ between platforms.

In some cases, these counts are helpful for the snapshot and should not be filtered.

pub fn with_filtered_cache_size(self) -> Self

Add extra filtering for cache size output

pub fn with_filtered_missing_file_error(self) -> Self

Add extra standard filtering for Windows-compatible missing file errors.

pub fn with_filtered_exe_suffix(self) -> Self

Add extra standard filtering for executable suffixes on the current platform e.g. drops .exe on Windows.

pub fn with_filtered_python_sources(self) -> Self

Add extra standard filtering for Python interpreter sources

pub fn with_filtered_python_names(self) -> Self

Add extra standard filtering for Python executable names, e.g., stripping version number and .exe suffixes.

pub fn with_filtered_virtualenv_bin(self) -> Self

Add extra standard filtering for venv executable directories on the current platform e.g. Scripts on Windows and bin on Unix.

pub fn with_filtered_python_install_bin(self) -> Self

Add extra standard filtering for Python installation bin/ directories, which are not present on Windows but are on Unix. See TestContext::with_filtered_virtualenv_bin for the virtual environment equivalent.

pub fn with_pyvenv_cfg_filters(self) -> Self

Filtering for various keys in a pyvenv.cfg file that will vary depending on the specific machine used:

• home = foo/bar/baz/python3.X.X/bin
• uv = X.Y.Z
• extends-environment = <path/to/parent/venv>

pub fn with_filtered_python_symlinks(self) -> Self

Add extra filtering for -> <PATH> symlink display for Python versions in the test context, e.g., for use in uv python list.

pub fn with_filtered_path(self, path: &Path, name: &str) -> Self

Add extra standard filtering for a given path.

pub fn with_filtered_link_mode_warning(self) -> Self

Adds a filter that specifically ignores the link mode warning.

This occurs in some cases and can be used on an ad hoc basis to squash the warning in the snapshots. This is useful because the warning does not consistently appear. It is dependent on the environment. (For example, sometimes it’s dependent on whether /tmp and ~/.local live on the same file system.)

pub fn with_filtered_not_executable(self) -> Self

Adds a filter for platform-specific errors when a file is not executable.

pub fn with_filtered_python_keys(self) -> Self

Adds a filter that ignores platform information in a Python installation key.

pub fn with_filtered_latest_python_versions(self) -> Self

Adds a filter that replaces the latest Python patch versions with [LATEST] placeholder.

pub fn with_filtered_windows_temp_dir(self) -> Self

Add a filter that ignores temporary directory in path.

pub fn with_filtered_compiled_file_count(self) -> Self

Add a filter for (bytecode) compilation file counts

pub fn with_cyclonedx_filters(self) -> Self

Adds filters for non-deterministic CycloneDX data

pub fn with_collapsed_whitespace(self) -> Self

Add a filter that collapses duplicate whitespace.

pub fn with_python_download_cache(self) -> Self

Use a shared global cache for Python downloads.

pub fn with_empty_python_install_mirror(self) -> Self

pub fn with_managed_python_dirs(self) -> Self

Add extra directories and configuration for managed Python installations.

pub fn with_versions_as_managed(self, versions: &[&str]) -> Self

pub fn with_filter(self, filter: (impl Into<String>, impl Into<String>)) -> Self

Add a custom filter to the TestContext.

pub fn with_unset_git_credential_helper(self) -> Self

pub fn clear_filters(self) -> Self

Clear filters on TestContext.

pub fn test_bucket_dir() -> PathBuf

Default to the canonicalized path to the temp directory. We need to do this because on macOS (and Windows on GitHub Actions) the standard temp dir is a symlink. (On macOS, the temporary directory is, like /var/..., which resolves to /private/var/....)

It turns out that, at least on macOS, if we pass a symlink as current_dir, it gets immediately resolved (such that if you call current_dir in the running Command, it returns resolved symlink). This breaks some snapshot tests, since we don’t want to resolve symlinks for user-provided paths.

pub fn new_with_versions_and_bin( python_versions: &[&str], uv_bin: PathBuf, ) -> Self

Create a new test context with multiple Python versions and explicit uv binary path.

Does not create a virtual environment by default, but the first Python version can be used to create a virtual environment with TestContext::create_venv.

This is called by the test_context_with_versions! macro.

pub fn command(&self) -> Command

Create a uv command for testing.

pub fn disallow_git_cli(bin_dir: &Path) -> Result<()>

pub fn with_git_lfs_config(self) -> Self

Setup Git LFS Filters

You can find the default filters in https://github.com/git-lfs/git-lfs/blob/v3.7.1/lfs/attribute.go#L66-L71 We set required to true to get a full stacktrace when these commands fail.

pub fn add_shared_options(&self, command: &mut Command, activate_venv: bool)

Shared behaviour for almost all test commands.

• Use a temporary cache directory
• Use a temporary virtual environment with the Python version of Self
• Don’t wrap text output based on the terminal we’re in, the test output doesn’t get printed but snapshotted to a string.
• Use a fake HOME to avoid accidentally changing the developer’s machine.
• Hide other Pythons with UV_PYTHON_INSTALL_DIR and installed interpreters with UV_TEST_PYTHON_PATH and an active venv (if applicable) by removing VIRTUAL_ENV.
• Increase the stack size to avoid stack overflows on windows due to large async functions.

pub fn add_shared_args(&self, command: &mut Command)

Only the arguments of TestContext::add_shared_options.

pub fn add_shared_env(&self, command: &mut Command, activate_venv: bool)

Only the environment variables of TestContext::add_shared_options.

pub fn pip_compile(&self) -> Command

Create a pip compile command for testing.

pub fn pip_sync(&self) -> Command

Create a pip compile command for testing.

pub fn pip_show(&self) -> Command

pub fn pip_freeze(&self) -> Command

Create a pip freeze command with options shared across scenarios.

pub fn pip_check(&self) -> Command

Create a pip check command with options shared across scenarios.

pub fn pip_list(&self) -> Command

pub fn venv(&self) -> Command

Create a uv venv command

pub fn pip_install(&self) -> Command

Create a pip install command with options shared across scenarios.

pub fn pip_uninstall(&self) -> Command

Create a pip uninstall command with options shared across scenarios.

pub fn pip_tree(&self) -> Command

Create a pip tree command for testing.

pub fn pip_debug(&self) -> Command

Create a pip debug command for testing.

pub fn help(&self) -> Command

Create a uv help command with options shared across scenarios.

pub fn init(&self) -> Command

Create a uv init command with options shared across scenarios and isolated from any git repository that may exist in a parent directory.

pub fn sync(&self) -> Command

Create a uv sync command with options shared across scenarios.

pub fn lock(&self) -> Command

Create a uv lock command with options shared across scenarios.

pub fn workspace_metadata(&self) -> Command

Create a uv workspace metadata command with options shared across scenarios.

pub fn workspace_dir(&self) -> Command

Create a uv workspace dir command with options shared across scenarios.

pub fn workspace_list(&self) -> Command

Create a uv workspace list command with options shared across scenarios.

pub fn export(&self) -> Command

Create a uv export command with options shared across scenarios.

pub fn format(&self) -> Command

Create a uv format command with options shared across scenarios.

pub fn build(&self) -> Command

Create a uv build command with options shared across scenarios.

pub fn version(&self) -> Command

pub fn self_version(&self) -> Command

pub fn self_update(&self) -> Command

pub fn publish(&self) -> Command

Create a uv publish command with options shared across scenarios.

pub fn python_find(&self) -> Command

Create a uv python find command with options shared across scenarios.

pub fn python_list(&self) -> Command

Create a uv python list command with options shared across scenarios.

pub fn python_install(&self) -> Command

Create a uv python install command with options shared across scenarios.

pub fn python_uninstall(&self) -> Command

Create a uv python uninstall command with options shared across scenarios.

pub fn python_upgrade(&self) -> Command

Create a uv python upgrade command with options shared across scenarios.

pub fn python_pin(&self) -> Command

Create a uv python pin command with options shared across scenarios.

pub fn python_dir(&self) -> Command

Create a uv python dir command with options shared across scenarios.

pub fn run(&self) -> Command

Create a uv run command with options shared across scenarios.

pub fn tool_run(&self) -> Command

Create a uv tool run command with options shared across scenarios.

pub fn tool_upgrade(&self) -> Command

Create a uv upgrade run command with options shared across scenarios.

pub fn tool_install(&self) -> Command

Create a uv tool install command with options shared across scenarios.

pub fn tool_list(&self) -> Command

Create a uv tool list command with options shared across scenarios.

pub fn tool_dir(&self) -> Command

Create a uv tool dir command with options shared across scenarios.

pub fn tool_uninstall(&self) -> Command

Create a uv tool uninstall command with options shared across scenarios.

pub fn add(&self) -> Command

Create a uv add command for the given requirements.

pub fn remove(&self) -> Command

Create a uv remove command for the given requirements.

pub fn tree(&self) -> Command

Create a uv tree command with options shared across scenarios.

pub fn clean(&self) -> Command

Create a uv cache clean command.

pub fn prune(&self) -> Command

Create a uv cache prune command.

pub fn cache_size(&self) -> Command

Create a uv cache size command.

pub fn build_backend(&self) -> Command

Create a uv build_backend command.

Note that this command is hidden and only invoking it through a build frontend is supported.

pub fn interpreter(&self) -> PathBuf

The path to the Python interpreter in the venv.

Don’t use this for Command::new, use Self::python_command instead.

pub fn python_command(&self) -> Command

pub fn auth_login(&self) -> Command

Create a uv auth login command.

pub fn auth_logout(&self) -> Command

Create a uv auth logout command.

pub fn auth_helper(&self) -> Command

Create a uv auth helper --protocol bazel get command.

pub fn auth_token(&self) -> Command

Create a uv auth token command.

pub fn with_real_home(self) -> Self

Set HOME to the real home directory.

We need this for testing commands which use the macOS keychain.

pub fn assert_command(&self, command: &str) -> Assert

Run the given python code and check whether it succeeds.

pub fn assert_file(&self, file: impl AsRef<Path>) -> Assert

Run the given python file and check whether it succeeds.

pub fn assert_installed(&self, package: &'static str, version: &'static str)

Assert a package is installed with the given version.

pub fn assert_not_installed(&self, package: &'static str)

Assert a package is not installed.

pub fn path_patterns(path: impl AsRef<Path>) -> Vec<String>

Generate various escaped regex patterns for the given path.

pub fn python_path(&self) -> OsString

pub fn filters(&self) -> Vec<(&str, &str)>

Standard snapshot filters plus those for this test context.

pub fn filters_without_standard_filters(&self) -> Vec<(&str, &str)>

Only the filters added to this test context.

pub fn python_kind(&self) -> &'static str

For when we add pypy to the test suite.

pub fn site_packages(&self) -> PathBuf

Returns the site-packages folder inside the venv.

pub fn reset_venv(&self)

Reset the virtual environment in the test context.

pub fn copy_ecosystem_project(&self, name: &str)

Copies the files from the ecosystem project given into this text context.

This will almost always write at least a pyproject.toml into this test context.

The given name should correspond to the name of a sub-directory (not a path to it) in the test/ecosystem directory.

This panics (fails the current test) for any failure.

pub fn diff_lock(&self, change: impl Fn(&Self) -> Command) -> String

Creates a way to compare the changes made to a lock file.

This routine starts by copying (not moves) the generated lock file to memory. It then calls the given closure with this test context to get a Command and runs the command. The diff between the old lock file and the new one is then returned.

This assumes that a lock has already been performed.

pub fn read(&self, file: impl AsRef<Path>) -> String

Read a file in the temporary directory