Expand description
Temp directories in tests
Improves on
tempdir
by adding several new features for testing:
- Allowing the user to cause the tests to use predictable paths
- Allowing the user to cause the tests to leave their temporary directories behind
- Helping ensure that test directories are not deleted before everything that uses them has been torn down (via Rust lifetimes)
The principal entrypoint is test_temp_dir!
which returns a TestTempDir
.
§Environment variables
The behaviour is influenced by TEST_TEMP_RETAIN
:
-
0
(or unset): use a temporary directory inTMPDIR
or/tmp
and try to delete it after the test completes (equivalent to usingtempfile::TempDir
). -
1
: use the directorytarget/test/crate::module::function
. Delete and recreate it on entry to the test, but do not delete it afterwards. On Windows,,
is used to replace::
since::
cannot appear in filenames. -
Pathname starting with
/
or.
: like1
, but the supplied path is used instead oftarget/test
.
§stdout printing
This is a crate for use in tests. When invoked, it will print a message to stdout about the test directory.
§Hazards of too-early deletion of temporary directories
When using raw tempfile
, or the untracked
methods in this crate,
it is easy to write test cases where the temporary directory might be deleted
while paths referring to it are still stored and ready for use
(for example in objects such as tor_keymgr::KeyMgr
or from tor_persist
).
Consequences would include the tests trying to refer to the now-deleted directory; in principle, this might even constitute a vulnerability, since an attacker might be able to replace the deleted directory with malicious data, and then the test case might read it!
The problem might even go undetected if the test case is such that “file not found” counts as a pass.
This can only happen if the TempDir
or TestTempDir
object is dropped too early.
The principal APIs in this crate use Rust lifetimes to help prevent that:
the temporary directory path is not directly accessible in 'static
form.
§Panics
This is a crate for use in tests. Most error conditions will cause a panic.
§Other crates
-
tempfile
: Underlying facility for raw temporary directories with auto-deletion; dependency of this crate. -
temp_testdir
: Similar to this crate, but rather less sophisticated. Doesn’t have the lifetime-based API, and has less predictable filenames.
Macros§
- Obtain a
TestTempDir
for the current test
Structs§
- A
T
which relies on some temporary directory with lifetimed
Enums§
- Directory for a test to store temporary files