1Test::Trap(3pm) User Contributed Perl Documentation Test::Trap(3pm)
2
6 Test::Trap - Trap exit codes, exceptions, output, etc.
7
9 Version 0.3.5
10
12 use Test::More;
13 use Test::Trap;
14 my @r = trap { some_code(@some_parameters) };
16 is ( $trap->exit, 1, 'Expecting &some_code to exit with 1' );
17 is ( $trap->stdout, '', 'Expecting no STDOUT' );
18 like ( $trap->stderr, qr/^Bad parameters; exiting\b/, 'Expecting warnings.' );
19
21 Primarily (but not exclusively) for use in test scripts: A block eval
22 on steroids, configurable and extensible, but by default trapping
23 (Perl) STDOUT, STDERR, warnings, exceptions, would-be exit codes, and
24 return values from boxed blocks of test code.
25 The values collected by the latest trap can then be queried or tested
27 through a special trap object.
28
30 A function and a scalar may be exported by any name. The function (by
31 default named "trap") is an analogue to block eval(), and the scalar
32 (by default named $trap) is the corresponding analogue to $@.
33 Optionally, you may specify the layers of the exported trap. Layers
35 may be specified by name, with a colon sigil. Multiple layers may be
36 given in a list, or just stringed together like ":flow:stderr:warn".
37 (For the advanced user, you may also specify anonymous layer
39 implementations -- i.e. an appropriate subroutine.)
40 See below for a list of the built-in layers, most of which are enabled
42 by default. Note, finally, that the ordering of the layers matter: The
43 :raw layer is always on the bottom (anything underneath it is ignored),
44 and any other "flow control" layers used should be right down there
45 with it.
46
48 trap BLOCK
49 This function may be exported by any name, but defaults to "trap".
50 By default, traps exceptions (like block eval), but also exits and exit
52 codes, returns and return values, context, and (Perl) output on STDOUT
53 or STDERR, and warnings. All information trapped can be queried
54 through the trap object, which is by default exported as $trap, but can
55 be exported by any name.
56 The value returned from "trap" mimics that returned from "eval": If
58 the BLOCK would die or exit, it returns an undefined value in scalar
59 context or an empty list in list context; otherwise it returns whatever
60 the BLOCK would return in the given context (also available as the
61 trapped return values).
62
64 Exactly what the "trap" traps depends on the layers of the trap. It is
65 possible to register more (see Test::Trap::Builder), but the following
66 layers are pre-defined by this module:
67 :raw
69 The only built-in terminating layer, at which the processing of the
70 layers stops, and the actual call to the user code is performed. On
71 success, it collects the return value(s) in the appropriate context.
72 Pushing the :raw layer on a trap will for most purposes remove all
73 layers below.
74 :die
76 The layer emulating block eval, trapping normal exceptions.
77 :exit
79 The third "flow control" layer, capturing exit codes if anything used
80 in the dynamic scope of the trap calls CORE::GLOBAL::exit(). (See
81 CAVEATS below for more.)
82 :flow
84 A shortcut for :raw:die:exit (effectively pushing all three layers on
85 the trap). Since this includes :raw, it is also terminating: Pushing
86 :flow on a trap will effectively remove all layers below.
87 :stdout, :stderr
89 Layers trapping Perl output on STDOUT and STDERR, respectively.
90 :stdout(perlio), :stderr(perlio)
92 As above, but specifying a capture strategy using PerlIO::scalar. If
93 this strategy is not available (typically if PerlIO is not), this is an
94 error. See "CAPTURE STRATEGIES".
95 :stdout(tempfile), :stderr(tempfile)
97 As above, but specifying a capture strategy using File::Temp. Note
98 that this is the default strategy, unless the :output() layer is used
99 to set another default. See "CAPTURE STRATEGIES".
100 :stdout(a;b;c), :stderr(a,b,c)
102 (Either syntax, commas or semicolons, is permitted, as is any number of
103 names in the list.) As above, but specifying the capture strategy by
104 the first existing name among a, b, and c. If no such strategy is
105 found, this is an error. See "CAPTURE STRATEGIES".
106 :warn
108 A layer trapping warnings, with additional tee: If STDERR is open, it
109 will also print the warnings there. (This output may be trapped by the
110 :stderr layer, be it above or below the :warn layer.)
111 :default
113 A short-cut for :raw:die:exit:stdout:stderr:warn (effectively pushing
114 all six layers on the trap). Since this includes :raw, it is also
115 terminating: Pushing :default on a trap will effectively remove all
116 layers below.
117 The other interesting property of :default is that it is what every
119 trap starts with: In order not to include the six layers that make up
120 :default, you need to push a terminating layer (such as :raw or :flow)
121 on the trap.
122 :on_fail(m)
124 A (non-default, non-trapping) layer that installs a callback method (by
125 name) m to be run on test failures. To run the "diag_all" method every
126 time a test fails:
127 use Test::Trap qw/ :on_fail(diag_all) /;
129 :void, :scalar, :list
131 These (non-default, non-trapping) layers will cause the trapped user
132 code to be run in void, scalar, or list context, respectively. (By
133 default, the trap will propagate context, that is, it will run the code
134 in whatever context the trap itself is in.)
135 If more than one of these layers are pushed on the trap, the deepest
137 (that is, leftmost) takes precedence:
138 use Test::Trap qw/ :scalar:void:list /;
140 trap { 42, 13 };
141 $trap->return_is_deeply( [ 13 ], 'Scalar comma.' );
142 :output(a;b;c)
144 A (non-default, non-trapping) layer that sets the default capture
145 strategy for any output trapping (":stdout", ":stderr", or other
146 similarly defined) layers below iton the trap.
147 use Test::Trap qw/ :output(systemsafe) /;
149 trap { system echo => 'Hello Unix!' }; # trapped!
150 use Test::Trap qw/ :flow:stderr:output(systemsafe):stdout /;
152 trap { system echo => 'Hello Unix!' }; # *not* trapped!
153 trap { system q/ echo 'Hello Unix!' >&2 / }; # trapped!
154 See "CAPTURE STRATEGIES".
156
158 How output is trapped, depends on the capture strategy used. It is
159 possible to register more (see Test::Trap::Builder), but the following
160 strategies are pre-defined by this module:
161 tempfile
163 The default capture strategy, provided by
164 Test::Trap::Builder::TempFile, in which output is temporarily
165 redirected to (and read back from) a tempfile.
166 tempfile-preserve
168 A variant of the capture strategy provided by
169 Test::Trap::Builder::TempFile, in which the handles used to write to
170 and read from the tempfile are both binmoded with the same perlio
171 layers as the trapped output handle originally had.
172 Caveat emptor: If the handle has perlio custom layers, they may (or may
174 not) fail to apply to the tempfile read and write handles.
175 systemsafe
177 A capture strategy provided by Test::Trap::Builder::SystemSafe, like
178 the default strategy, except it outputs on file handles with the same
179 file descriptors as the trapped output handle originally had, and so
180 can be used to trap output from forked-off processes, including
181 system().
182 This strategy may be "safe" in relation to forked-off processes, but it
184 is fragile. For one, it only works with handles that have "real" file
185 descriptors. For another, it depends on the original file descriptors
186 being available after closing. (If signal handlers or threads open
187 files, they may well not be.) And it may fail in other ways. But in
188 relation to forked-off processes, the other pre-defined strategies will
189 silently fail to trap, as will similarly simple strategies. This one,
190 when not crashing, will trap that output.
191 systemsafe-preserve
193 A variant of the capture strategy provided by
194 Test::Trap::Builder::SystemSafe, in which the handles used to write to
195 and read from the tempfile are both binmoded with the same perlio
196 layers as the trapped output handle originally had.
197 Caveat emptor: If the handle has perlio custom layers, they may (or may
199 not) fail to apply to the tempfile read and write handles.
200 perlio
202 A capture strategy provided by Test::Trap::Builder::PerlIO, in which
203 output is temporarily redirected to an in-memory file via
204 PerlIO::scalar.
205 If PerlIO::scalar is not available, neither is this strategy.
207
209 The following methods may be called on the trap objects after any trap
210 has been sprung, and access the outcome of the run.
211 Any property will be undef if not actually trapped -- whether because
213 there is no layer to trap them or because flow control passed them by.
214 (If there is an active and successful trap layer, empty strings and
215 empty arrays trapped will of course be defined.)
216 When properties are set, their values will be as follows:
218 leaveby
220 A string indicating how the trap terminated: "return", "die", or
221 "exit".
222 die
224 The exception, if the latest trap threw one.
225 exit
227 The exit code, if the latest trap tried to exit (by way of the trap's
228 own &CORE::GLOBAL::exit only; see "CAVEATS").
229 return [INDEX ...]
231 Returns undef if the latest trap did not terminate with a return;
232 otherwise returns three different views of the return array:
233 • if no INDEX is passed, returns a reference to the array (NB! an
235 empty array of indices qualifies as "no index")
236 • if called with at least one INDEX in scalar context, returns the
238 array element indexed by the first INDEX (ignoring the rest)
239 • if called with at least one INDEX in list context, returns the
241 slice of the array by these indices
242 Note: The array will hold but a single value if the trap was sprung in
244 scalar context, and will be empty if it was in void context.
245 stdout, stderr
247 The captured output on the respective file handles.
248 warn [INDEX]
250 Returns undef if the latest trap had no warning-trapping layer;
251 otherwise returns three different views of the warn array:
252 • if no INDEX is passed, returns a reference to the array (NB! an
254 empty array of indices qualifies as "no index")
255 • if called with at least one INDEX in scalar context, returns the
257 array element indexed by the first INDEX (ignoring the rest)
258 • if called with at least one INDEX in list context, returns the
260 slice of the array by these indices
261 wantarray
263 The context in which the latest code trapped was called. (By default a
264 propagated context, but layers can override this.)
265 list, scalar, void
267 True if the latest code trapped was called in the indicated context.
268 (By default the code will be called in a propagated context, but layers
269 can override this.)
270
272 For each accessor, a number of convenient standard test methods are
273 also available. By default, these are a few standard tests from
274 Test::More, plus the "nok" test (a negated "ok" test). All for
275 convenience:
276 ACCESSOR_ok [INDEX,] TEST_NAME
278 ACCESSOR_nok [INDEX,] TEST_NAME
279 ACCESSOR_is [INDEX,] SCALAR, TEST_NAME
280 ACCESSOR_isnt [INDEX,] SCALAR, TEST_NAME
281 ACCESSOR_isa_ok [INDEX,] SCALAR, INVOCANT_NAME
282 ACCESSOR_like [INDEX,] REGEX, TEST_NAME
283 ACCESSOR_unlike [INDEX,] REGEX, TEST_NAME
284 ACCESSOR_is_deeply STRUCTURE, TEST_NAME
285 INDEX is not optional: It is required for array accessors (like
286 "return" and "warn"), and disallowed for scalar accessors. Note that
287 the "is_deeply" test does not accept an index. Even for array
288 accessors, it operates on the entire array.
289 For convenience and clarity, tests against a flow control ACCESSOR
291 ("return", "die", "exit", or any you define yourself) will first test
292 whether the trap was left by way of the flow control mechanism in
293 question, and fail with appropriate diagnostics otherwise.
294 did_die, did_exit, did_return
296 Conveniences: Tests whether the trap was left by way of the flow
297 control mechanism in question. Much like leaveby_is('die') etc, but
298 with better diagnostics and (run-time) spell checking.
299 quiet
301 Convenience: Passes if zero-length output was trapped on both STDOUT
302 and STDERR, and generate better diagnostics otherwise.
303
305 diag_all
306 Prints a diagnostic message (as per "diag" in Test::More) consisting of
307 a dump (in Perl code, as per Data::Dump) of the trap object.
308 diag_all_once
310 As "diag_all", except if this instance of the trap object has already
311 been diag_all_once'd, the diagnostic message will instead consist of
312 the string "(as above)".
313 This could be useful with the "on_fail" layer:
315 use Test::Trap qw/ :on_fail(diag_all_once) /;
317
319 This module must be loaded before any code containing exit()s to be
320 trapped is compiled. Any exit() already compiled won't be trappable,
321 and will terminate the program anyway.
322 This module overrides &CORE::GLOBAL::exit, so may not work correctly
324 (or even at all) in the presence of other code overriding
325 &CORE::GLOBAL::exit. More precisely: This module installs its own
326 exit() on entry of the block, and restores the previous one, if any,
327 only upon leaving the block.
328 If you use fork() in the dynamic scope of a trap, beware that the
330 (default) :exit layer of that trap does not trap exit() in the
331 children, but passes them to the outer handler. If you think about it,
332 this is what you are likely to want it to do in most cases.
333 Note that the (default) :exit layer only traps &CORE::GLOBAL::exit
335 calls (and bare exit() calls that compile to that). It makes no
336 attempt to trap CORE::exit(), POSIX::_exit(), exec(), untrapped
337 exceptions from die(), nor segfault. Nor does it attempt to trap
338 anything else that might terminate the program. The trap is a block
339 eval on steroids -- not the last block eval of Krypton!
340 This module traps warnings using $SIG{__WARN__}, so may not work
342 correctly (or even at all) in the presence of other code setting this
343 handler. More precisely: This module installs its own __WARN__ handler
344 on entry of the block, and restores the previous one, if any, only upon
345 leaving the block.
346 The (default) :stdout and :stderr handlers will not trap output from
348 system() calls.
349 Threads? No idea. It might even work correctly.
351
353 Please report any bugs or feature requests directly to the author.
354
356 Eirik Berg Hanssen, "<ebhanssen@cpan.org>"
357
359 Copyright 2006-2014 Eirik Berg Hanssen, All Rights Reserved.
360 This program is free software; you can redistribute it and/or modify it
362 under the same terms as Perl itself.
363perl v5.38.0 2023-07-21 Test::Trap(3pm)