Test::T...ir::Tiny(3)

💅 Test::TempDir::Tiny — like, the whole manual, bestie ✨

Okay so you're looking at the Test::T...ir::Tiny(3) page (the truncated name is just the man page being dramatic about column width, it's Test::TempDir::Tiny, we been knew 🎀). Version 0.018, and it's about to make your test suite SO much less annoying. Let's go 🦋

---

✨ NAME ✨

Test::TempDir::Tiny — temporary directories that stick around when tests fail 💀✨

🌸 VERSION 🌸

version 0.018

🎀 SYNOPSIS 🎀

# t/foo.t
use Test::More;
use Test::TempDir::Tiny;

# default tempdirs
$dir = tempdir();          # ./tmp/t_foo_t/default_1/
$dir = tempdir();          # ./tmp/t_foo_t/default_2/

# labeled tempdirs
$dir = tempdir("label");   # ./tmp/t_foo_t/label_1/
$dir = tempdir("label");   # ./tmp/t_foo_t/label_2/

# labels with spaces and non-word characters
$dir = tempdir("bar baz")  # ./tmp/t_foo_t/bar_baz_1/
$dir = tempdir("!!!bang")  # ./tmp/t_foo_t/_bang_1/

# run code in a temporary directory
in_tempdir "label becomes name" => sub {
    my $cwd = shift;
    # do stuff in a tempdir
};

💖 DESCRIPTION 💖

So this module teams up with Test::More to make temporary directories that stay put if your tests fail. Iconic behavior, honestly 👑

It's loosely based on Test::TempDir — but with less complexity, greater portability, and zero non-core dependencies. (It does recommend Capture::Tiny for testing, fyi 🫶)

The tempdir and in_tempdir functions are exported by default. No qw() gymnastics needed, periodt.

If your current directory is writable, the root for all these directories will be ./tmp. If it's not writable, a File::Temp directory gets created wherever temporary directories are stored for your system. Either way you're covered ✨

Every *.t file gets its own little subdirectory under that root, named after the test filename — but with slashes and periods swapped out for underscores. So t/foo.t gets its very own test-file-specific subdirectory ./tmp/t_foo_t/. Directories made by tempdir go inside that. Which means when tests fail you can actually find your files later instead of crying. Life-changing 🌈

The test-file-specific name is consistent from run-to-run. And if an old directory already exists? It gets removed. Fresh slate, bestie 🧚

When the test file exits and all tests passed, that test-file-specific directory gets recursively yeeted.

If a test failed and the root is ./tmp, the test-file-specific directory sticks around so you can go inspect it 👀 (But if the root is a File::Temp directory, it's always discarded — no exceptions).

And if nothing is left in ./tmp (meaning no other test file failed), then ./tmp gets cleaned up too — unless it's a symlink. Respect the symlink 🫡

This module also tries to avoid race conditions from parallel testing. In extreme cases, the test-file-specific subdirectory might get created as a regular File::Temp directory instead of in ./tmp. If that happens, you'll get a warning. Not a crash, just a heads up 💅

🔥 FUNCTIONS 🔥

⭐ tempdir

$dir = tempdir();          # .../default_1/
$dir = tempdir("label");   # .../label_1/

Creates a directory underneath a test-file-specific temporary directory and returns the absolute path to it, in platform-native form (i.e. with backslashes on Windows 🪟).

The function takes a single argument as a label for the directory, or defaults to "default". An incremental counter value gets appended so you can reuse the same label in a loop and still get distinct temporary directories:

# t/foo.t

for ( 1 .. 3 ) {
    tempdir("in loop");
}

# creates:
#   ./tmp/t_foo_t/in_loop_1
#   ./tmp/t_foo_t/in_loop_2
#   ./tmp/t_foo_t/in_loop_3

If the label has any characters besides alphanumerics, underscore and dash, they get collapsed and replaced with a single underscore:

$dir = tempdir("a space"); # .../a_space_1/
$dir = tempdir("a!bang");  # .../a_bang_1/

The test-file-specific directory and everything inside it gets cleaned up in an END block if the current test file passes its tests 🎉

🦋 in_tempdir

in_tempdir "label becomes name" => sub {
    my $cwd = shift;
    # this happens in tempdir
};

Give it a label and a code reference, and it creates a temporary directory based on that label (following the same rules as tempdir), changes into that directory, runs your code, then changes back to the original directory. Chef's kiss 👩‍🍳

The temporary directory path gets passed as an argument to your code reference.

When the code finishes — even if it dies — in_tempdir will change back to the original directory if it can, or to the root if it can't, and it will rethrow any fatal errors. It's giving responsible main character energy 💜

🌟 ENVIRONMENT 🌟

🌸 PERL_TEST_TEMPDIR_TINY_NOCLEANUP

When this environment variable is true, directories will not be cleaned up — even if tests pass. You want the mess? You get the mess, bestie 🍓

👑 SEE ALSO 👑

• File::Temp
• Path::Tiny

💀 SUPPORT 💀

🙈 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/Test-TempDir-Tiny/issues>. You'll be notified automatically of any progress on your issue — no refreshing required 📬

🧚 Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<https://github.com/dagolden/Test-TempDir-Tiny>

git clone https://github.com/dagolden/Test-TempDir-Tiny.git

⭐ AUTHOR ⭐

David Golden <dagolden@cpan.org>

💖 CONTRIBUTORS 💖

• Christian Walde <walde.christian@googlemail.com>
• Kent Fredric <kentfredric@gmail.com>
• Shawn Laffan <shawnlaffan@gmail.com>
• Sven Kirmess <sven.kirmess@kzone.ch>

🌈 COPYRIGHT AND LICENSE 🌈

This software is Copyright (c) 2014 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page, no cap 💅 — this was Test::TempDir::Tiny version 0.018, rendered from the perl v5.42.0 toolchain, dated 2018-09-20. go forth and never debug a vanished tempdir again, ily 🫶✨