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