Debian Codegraph @

README

raw
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