| 1 |
NAME |
| 2 |
Test::TempDir::Tiny - Temporary directories that stick around when tests |
| 3 |
fail |
| 4 |
|
| 5 |
VERSION |
| 6 |
version 0.018 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
# t/foo.t |
| 10 |
use Test::More; |
| 11 |
use Test::TempDir::Tiny; |
| 12 |
|
| 13 |
# default tempdirs |
| 14 |
$dir = tempdir(); # ./tmp/t_foo_t/default_1/ |
| 15 |
$dir = tempdir(); # ./tmp/t_foo_t/default_2/ |
| 16 |
|
| 17 |
# labeled tempdirs |
| 18 |
$dir = tempdir("label"); # ./tmp/t_foo_t/label_1/ |
| 19 |
$dir = tempdir("label"); # ./tmp/t_foo_t/label_2/ |
| 20 |
|
| 21 |
# labels with spaces and non-word characters |
| 22 |
$dir = tempdir("bar baz") # ./tmp/t_foo_t/bar_baz_1/ |
| 23 |
$dir = tempdir("!!!bang") # ./tmp/t_foo_t/_bang_1/ |
| 24 |
|
| 25 |
# run code in a temporary directory |
| 26 |
in_tempdir "label becomes name" => sub { |
| 27 |
my $cwd = shift; |
| 28 |
# do stuff in a tempdir |
| 29 |
}; |
| 30 |
|
| 31 |
DESCRIPTION |
| 32 |
This module works with Test::More to create temporary directories that |
| 33 |
stick around if tests fail. |
| 34 |
|
| 35 |
It is loosely based on Test::TempDir, but with less complexity, greater |
| 36 |
portability and zero non-core dependencies. (Capture::Tiny is |
| 37 |
recommended for testing.) |
| 38 |
|
| 39 |
The "tempdir" and "in_tempdir" functions are exported by default. |
| 40 |
|
| 41 |
If the current directory is writable, the root for directories will be |
| 42 |
./tmp. Otherwise, a File::Temp directory will be created wherever |
| 43 |
temporary directories are stored for your system. |
| 44 |
|
| 45 |
Every *.t file gets its own subdirectory under the root based on the |
| 46 |
test filename, but with slashes and periods replaced with underscores. |
| 47 |
For example, t/foo.t would get a test-file-specific subdirectory |
| 48 |
./tmp/t_foo_t/. Directories created by "tempdir" get put in that |
| 49 |
directory. This makes it very easy to find files later if tests fail. |
| 50 |
|
| 51 |
The test-file-specific name is consistent from run-to-run. If an old |
| 52 |
directory already exists, it will be removed. |
| 53 |
|
| 54 |
When the test file exits, if all tests passed, then the |
| 55 |
test-file-specific directory is recursively removed. |
| 56 |
|
| 57 |
If a test failed and the root directory is ./tmp, the test-file-specific |
| 58 |
directory sticks around for inspection. (But if the root is a File::Temp |
| 59 |
directory, it is always discarded). |
| 60 |
|
| 61 |
If nothing is left in ./tmp (i.e. no other test file failed), then ./tmp |
| 62 |
is cleaned up as well (unless it's a symlink). |
| 63 |
|
| 64 |
This module attempts to avoid race conditions due to parallel testing. |
| 65 |
In extreme cases, the test-file-specific subdirectory might be created |
| 66 |
as a regular File::Temp directory rather than in ./tmp. In such a case, |
| 67 |
a warning will be issued. |
| 68 |
|
| 69 |
FUNCTIONS |
| 70 |
tempdir |
| 71 |
$dir = tempdir(); # .../default_1/ |
| 72 |
$dir = tempdir("label"); # .../label_1/ |
| 73 |
|
| 74 |
Creates a directory underneath a test-file-specific temporary directory |
| 75 |
and returns the absolute path to it in platform-native form (i.e. with |
| 76 |
backslashes on Windows). |
| 77 |
|
| 78 |
The function takes a single argument as a label for the directory or |
| 79 |
defaults to "default". An incremental counter value will be appended to |
| 80 |
allow a label to be used within a loop with distinct temporary |
| 81 |
directories: |
| 82 |
|
| 83 |
# t/foo.t |
| 84 |
|
| 85 |
for ( 1 .. 3 ) { |
| 86 |
tempdir("in loop"); |
| 87 |
} |
| 88 |
|
| 89 |
# creates: |
| 90 |
# ./tmp/t_foo_t/in_loop_1 |
| 91 |
# ./tmp/t_foo_t/in_loop_2 |
| 92 |
# ./tmp/t_foo_t/in_loop_3 |
| 93 |
|
| 94 |
If the label contains any characters besides alphanumerics, underscore |
| 95 |
and dash, they will be collapsed and replaced with a single underscore. |
| 96 |
|
| 97 |
$dir = tempdir("a space"); # .../a_space_1/ |
| 98 |
$dir = tempdir("a!bang"); # .../a_bang_1/ |
| 99 |
|
| 100 |
The test-file-specific directory and all directories within it will be |
| 101 |
cleaned up with an END block if the current test file passes tests. |
| 102 |
|
| 103 |
in_tempdir |
| 104 |
in_tempdir "label becomes name" => sub { |
| 105 |
my $cwd = shift; |
| 106 |
# this happens in tempdir |
| 107 |
}; |
| 108 |
|
| 109 |
Given a label and a code reference, creates a temporary directory based |
| 110 |
on the label (following the rules of "tempdir"), changes to that |
| 111 |
directory, runs the code, then changes back to the original directory. |
| 112 |
|
| 113 |
The temporary directory path is given as an argument to the code |
| 114 |
reference. |
| 115 |
|
| 116 |
When the code finishes (even if it dies), "in_tempdir" will change back |
| 117 |
to the original directory if it can, to the root if it can't, and will |
| 118 |
rethrow any fatal errors. |
| 119 |
|
| 120 |
ENVIRONMENT |
| 121 |
"PERL_TEST_TEMPDIR_TINY_NOCLEANUP" |
| 122 |
When this environment variable is true, directories will not be cleaned |
| 123 |
up, even if tests pass. |
| 124 |
|
| 125 |
SEE ALSO |
| 126 |
* File::Temp |
| 127 |
|
| 128 |
* Path::Tiny |
| 129 |
|
| 130 |
SUPPORT |
| 131 |
Bugs / Feature Requests |
| 132 |
Please report any bugs or feature requests through the issue tracker at |
| 133 |
<https://github.com/dagolden/Test-TempDir-Tiny/issues>. You will be |
| 134 |
notified automatically of any progress on your issue. |
| 135 |
|
| 136 |
Source Code |
| 137 |
This is open source software. The code repository is available for |
| 138 |
public review and contribution under the terms of the license. |
| 139 |
|
| 140 |
<https://github.com/dagolden/Test-TempDir-Tiny> |
| 141 |
|
| 142 |
git clone https://github.com/dagolden/Test-TempDir-Tiny.git |
| 143 |
|
| 144 |
AUTHOR |
| 145 |
David Golden <[email protected]> |
| 146 |
|
| 147 |
CONTRIBUTORS |
| 148 |
* Christian Walde <[email protected]> |
| 149 |
|
| 150 |
* Kent Fredric <[email protected]> |
| 151 |
|
| 152 |
* Shawn Laffan <[email protected]> |
| 153 |
|
| 154 |
* Sven Kirmess <[email protected]> |
| 155 |
|
| 156 |
COPYRIGHT AND LICENSE |
| 157 |
This software is Copyright (c) 2014 by David Golden. |
| 158 |
|
| 159 |
This is free software, licensed under: |
| 160 |
|
| 161 |
The Apache License, Version 2.0, January 2004 |
| 162 |
|