1Test::TempDir::Tiny(3)User Contributed Perl DocumentationTest::TempDir::Tiny(3)
2
3
4

NAME

6       Test::TempDir::Tiny - Temporary directories that stick around when
7       tests fail
8

VERSION

10       version 0.018
11

SYNOPSIS

13           # t/foo.t
14           use Test::More;
15           use Test::TempDir::Tiny;
16
17           # default tempdirs
18           $dir = tempdir();          # ./tmp/t_foo_t/default_1/
19           $dir = tempdir();          # ./tmp/t_foo_t/default_2/
20
21           # labeled tempdirs
22           $dir = tempdir("label");   # ./tmp/t_foo_t/label_1/
23           $dir = tempdir("label");   # ./tmp/t_foo_t/label_2/
24
25           # 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
29           # 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

DESCRIPTION

36       This module works with Test::More to create temporary directories that
37       stick around if tests fail.
38
39       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
43       The "tempdir" and "in_tempdir" functions are exported by default.
44
45       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
49       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
55       The test-file-specific name is consistent from run-to-run.  If an old
56       directory already exists, it will be removed.
57
58       When the test file exits, if all tests passed, then the test-file-
59       specific directory is recursively removed.
60
61       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
65       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
68       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

FUNCTIONS

74   tempdir
75           $dir = tempdir();          # .../default_1/
76           $dir = tempdir("label");   # .../label_1/
77
78       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
82       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
87           # t/foo.t
88
89           for ( 1 .. 3 ) {
90               tempdir("in loop");
91           }
92
93           # 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
98       If the label contains any characters besides alphanumerics, underscore
99       and dash, they will be collapsed and replaced with a single underscore.
100
101           $dir = tempdir("a space"); # .../a_space_1/
102           $dir = tempdir("a!bang");  # .../a_bang_1/
103
104       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
107   in_tempdir
108           in_tempdir "label becomes name" => sub {
109               my $cwd = shift;
110               # this happens in tempdir
111           };
112
113       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
117       The temporary directory path is given as an argument to the code
118       reference.
119
120       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

ENVIRONMENT

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

SEE ALSO

130       •   File::Temp
131
132       •   Path::Tiny
133

SUPPORT

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
140   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
144       <https://github.com/dagolden/Test-TempDir-Tiny>
145
146         git clone https://github.com/dagolden/Test-TempDir-Tiny.git
147

AUTHOR

149       David Golden <dagolden@cpan.org>
150

CONTRIBUTORS

152       •   Christian Walde <walde.christian@googlemail.com>
153
154       •   Kent Fredric <kentfredric@gmail.com>
155
156       •   Shawn Laffan <shawnlaffan@gmail.com>
157
158       •   Sven Kirmess <sven.kirmess@kzone.ch>
159
161       This software is Copyright (c) 2014 by David Golden.
162
163       This is free software, licensed under:
164
165         The Apache License, Version 2.0, January 2004
166
167
168
169perl v5.34.0                      2022-01-21            Test::TempDir::Tiny(3)
Impressum