Enum TestTempDir

#[non_exhaustive]
pub enum TestTempDir {
    Ephemeral(TempDir),
    Persistent(PathBuf),
}

Directory for a test to store temporary files

Automatically deleted (if appropriate) when dropped.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Ephemeral(TempDir)

An ephemeral directory

Persistent(PathBuf)

A directory which should persist after the test completes

Implementations

impl TestTempDir

pub fn from_module_path_and_thread(mod_path: &str) -> TestTempDir

Obtain a temp dir named after our thread, and the module path mod_path

Expects that the current thread name is the module path within the crate, followed by the test function name. (This is how Rust’s builtin #[test] names its threads.) And, expects that mod_path is the crate name, and then the module path within the crate. This is what Rust’s builtin module_path! macro returns.

The two instances of the module path within the crate must be the same!

Panics

Panics if the thread name and mod_path do not correspond (see the self(module-level documentation).)

pub fn from_complete_item_path(item_path: &str) -> Self

Obtains a temp dir named after a complete item path

The supplied item_path must be globally unique in the whole workspace, or it might collide with other tests from other crates.

Handles the replacement of :: with , on Windows.

pub fn from_stable_unique_subdir(subdir: &str) -> Self

Obtains a temp dir given a stable unique subdirectory name

The supplied subdir must be globally unique across every test in the whole workspace, or it might collide with other tests.

pub fn as_path_untracked(&self) -> &Path

Obtain a reference to the Path of this temp directory

Prefer to use .used_by() where possible.

The lifetime of the temporary directory will not be properly represented by Rust lifetimes. For example, calling .to_owned()ToOwned::to_owned will get a 'static value, which doesn’t represent the fact that the directory will go away when the TestTempDir is dropped.

So the resulting value can be passed to functions which store the path for later use, and might later malfunction because the TestTempDir is dropped too early.

pub fn subdir_untracked(&self, subdir: &str) -> PathBuf

Return a subdirectory, without lifetime tracking

pub fn used_by<'d, T>( &'d self, f: impl FnOnce(&Path) -> T, ) -> TestTempDirGuard<'d, T>

Obtain a T which uses paths in self

Within f, construct T using the supplied filesystem path, which is the full path to the test’s temporary directory.

Do not store or copy the path anywhere other than the return value; such copies would not be protected by Rust lifetimes against early deletion.

Rust lifetime tracking ensures that the temporary directory won’t be cleaned up until the T is destroyed.

pub fn subdir_used_by<'d, T>( &'d self, subdir: &str, f: impl FnOnce(PathBuf) -> T, ) -> TestTempDirGuard<'d, T>

Obtain a T which uses paths in a subdir of self

The directory subdir will be created, within the test’s temporary directory, if it doesn’t already exist.

Within f, construct T using the supplied filesystem path, which is the fuill path to the subdirectory.

Do not store or copy the path anywhere other than the return value; such copies would not be protected by Rust lifetimes against early deletion.

Rust lifetime tracking ensures that the temporary directory won’t be cleaned up until the T is destroyed.

Trait Implementations

impl Debug for TestTempDir

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.