1Test::Trap(3) User Contributed Perl Documentation Test::Trap(3)
2
6 Test::Trap - Trap exit codes, exceptions, output, etc.
7
9 Version 0.2.1
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
58 Exactly what the "trap" traps depends on the layers of the trap. It is
59 possible to register more (see Test::Trap::Builder), but the following
60 layers are pre-defined by this module:
61 :raw
63 The terminating layer, at which the processing of the layers stops, and
64 the actual call to the user code is performed. On success, it collects
65 the return value(s) in the appropriate context. Pushing the :raw layer
66 on a trap will for most purposes remove all layers below.
67 :die
69 The layer emulating block eval, capturing normal exceptions.
70 :exit
72 The third "flow control" layer, capturing exit codes if anything used
73 in the dynamic scope of the trap calls CORE::GLOBAL::exit(). (See
74 CAVEATS below for more.)
75 :flow
77 A pseudo-layer shortcut for :raw:die:exit. Since this includes :raw,
78 pushing :flow on a trap will remove all layers below.
79 :stdout, :stderr
81 Layers trapping Perl output on STDOUT and STDERR, respectively.
82 :stdout(perlio), :stderr(perlio)
84 As above, but specifying a backend implemented using PerlIO::scalar.
85 If this backend is not available (typically if PerlIO is not), this is
86 an error.
87 :stdout(tempfile), :stderr(tempfile)
89 As above, but specifying a backend implemented using File::Temp. Note
90 that this is the default implementation, unless the ":output()" layer
91 is used to set another default.
92 :stdout(a;b;c), :stderr(a,b,c)
94 (Either syntax, commas or semicolons, is permitted, as is any number of
95 names in the list.) As above, but specifying the backend
96 implementation by the first existing name among a, b, and c. If no
97 such implementation is available, this is an error.
98 :warn
100 A layer trapping warnings, with additional tee: If STDERR is open, it
101 will also print the warnings there. (This output may be trapped by the
102 :stderr layer, be it above or below the :warn layer.)
103 :default
105 A pseudo-layer short-cut for :raw:die:exit:stdout:stderr:warn. Since
106 this includes :raw, pushing :default on a trap will remove all layers
107 below. The other interesting property of :default is that it is what
108 every trap starts with: In order not to include any of the six layers
109 that make up :default, you need to push a terminating layer (such as
110 :raw or :flow) on the trap.
111 :on_fail(m)
113 A (non-default) pseudo-layer that installs a callback method (by name)
114 m to be run on test failures. To run the "diag_all" method every time
115 a test fails:
116 use Test::Trap qw/ :on_fail(diag_all) /;
118 :void, :scalar, :list
120 Runs the trapped user code in void, scalar, or list context,
121 respectively. (By default, the code is run in whatever context the
122 trap itself is in.)
123 If more than one of these layers are pushed on the trap, the deepest
125 (that is, leftmost) takes precedence:
126 use Test::Trap qw/ :scalar:void:list /;
128 trap { 42, 13 };
129 $trap->return_is_deeply( [ 13 ], 'Scalar comma.' );
130 :output(a;b;c)
132 A (non-default) pseudo-layers that sets the default backend layer
133 implementation for any output trapping (":stdout", ":stderr", or other
134 similarly defined) layers already on the trap.
135 use Test::Trap qw/ :output(systemsafe) /;
137 trap { system echo => 'Hello Unix!' }; # trapped!
138
140 The following methods may be called on the trap objects after any trap
141 has been sprung, and access the outcome of the run.
142 Any property will be undef if not actually trapped -- whether because
144 there is no layer to trap them or because flow control passed them by.
145 (If there is an active and successful trap layer, empty strings and
146 empty arrays trapped will of course be defined.)
147 When properties are set, their values will be as follows:
149 leaveby
151 A string indicating how the trap terminated: "return", "die", or
152 "exit".
153 die
155 The exception, if the latest trap threw one.
156 exit
158 The exit code, if the latest trap tried to exit.
159 return [INDEX ...]
161 Returns undef if the latest trap did not terminate with a return;
162 otherwise returns three different views of the return array:
163 · if no INDEX is passed, returns a reference to the array (NB! an
165 empty array of indices qualifies as "no index")
166 · if called with at least one INDEX in scalar context, returns the
168 array element indexed by the first INDEX (ignoring the rest)
169 · if called with at least one INDEX in list context, returns the
171 slice of the array by these indices
172 Note: The array will hold but a single value if the trap was sprung in
174 scalar context, and will be empty if it was in void context.
175 stdout, stderr
177 The captured output on the respective file handles.
178 warn [INDEX]
180 Returns undef if the latest trap had no warning-trapping layer;
181 otherwise returns three different views of the warn array:
182 · if no INDEX is passed, returns a reference to the array (NB! an
184 empty array of indices qualifies as "no index")
185 · if called with at least one INDEX in scalar context, returns the
187 array element indexed by the first INDEX (ignoring the rest)
188 · if called with at least one INDEX in list context, returns the
190 slice of the array by these indices
191 wantarray
193 The context in which the latest code trapped was called. (By default a
194 propagated context, but layers can override this.)
195 list, scalar, void
197 True if the latest code trapped was called in the indicated context.
198 (By default the code will be called in a propagated context, but layers
199 can override this.)
200
202 For each accessor, a number of convenient standard test methods are
203 also available. By default, these are a few standard tests from
204 Test::More, plus the "nok" test (a negated "ok" test). All for
205 convenience:
206 ACCESSOR_ok [INDEX,] TEST_NAME
208 ACCESSOR_nok [INDEX,] TEST_NAME
209 ACCESSOR_is [INDEX,] SCALAR, TEST_NAME
210 ACCESSOR_isnt [INDEX,] SCALAR, TEST_NAME
211 ACCESSOR_isa_ok [INDEX,] SCALAR, INVOCANT_NAME
212 ACCESSOR_like [INDEX,] REGEX, TEST_NAME
213 ACCESSOR_unlike [INDEX,] REGEX, TEST_NAME
214 ACCESSOR_is_deeply STRUCTURE, TEST_NAME
215 INDEX is not optional: It is required for array accessors (like
216 "return" and "warn"), and disallowed for scalar accessors. Note that
217 the "is_deeply" test does not accept an index. Even for array
218 accessors, it operates on the entire array.
219 For convenience and clarity, tests against a flow control ACCESSOR
221 ("return", "die", "exit", or any you define yourself) will first test
222 whether the trap was left by way of the flow control mechanism in
223 question, and fail with appropriate diagnostics otherwise.
224 did_die, did_exit, did_return
226 Conveniences: Tests whether the trap was left by way of the flow
227 control mechanism in question. Much like "leaveby_is('die')" etc, but
228 with better diagnostics and (run-time) spell checking.
229 quiet
231 Convenience: Passes if zero-length output was trapped on both STDOUT
232 and STDERR, and generate better diagnostics otherwise.
233
235 diag_all
236 Prints a diagnostic message (as per "diag" in Test::More) consisting of
237 a dump (in Perl code, as per Data::Dump) of the trap object.
238 diag_all_once
240 As "diag_all", except if this instance of the trap object has already
241 been diag_all_once'd, the diagnostic message will instead consist of
242 the string "(as above)".
243 This could be useful with the "on_fail" layer:
245 use Test::Trap qw/ :on_fail(diag_all_once) /;
247
249 This module must be loaded before any code containing exit()s to be
250 trapped is compiled. Any exit() already compiled won't be trappable,
251 and will terminate the program anyway.
252 This module overrides &CORE::GLOBAL::exit, so may not work correctly
254 (or even at all) in the presence of other code overriding
255 &CORE::GLOBAL::exit. More precisely: This module installs its own
256 exit() on entry of the block, and restores the previous one, if any,
257 only upon leaving the block.
258 If you use fork() in the dynamic scope of a trap, beware that the
260 (default) :exit layer of that trap does not trap exit() in the
261 children, but passes them to the outer handler. If you think about it,
262 this is what you are likely to want it to do in most cases.
263 Note that the (default) :exit layer only traps &CORE::GLOBAL::exit
265 calls (and bare exit() calls that compile to that). It makes no
266 attempt to trap CORE::exit(), POSIX::_exit(), exec(), nor segfault.
267 Nor does it attempt to trap anything else that might terminate the
268 program. The trap is a block eval on steroids -- not the last block
269 eval of Krypton!
270 This module traps warnings using $SIG{__WARN__}, so may not work
272 correctly (or even at all) in the presence of other code setting this
273 handler. More precisely: This module installs its own __WARN__ handler
274 on entry of the block, and restores the previous one, if any, only upon
275 leaving the block.
276 The (default) :stdout and :stderr handlers will not trap output from
278 system() calls.
279 Threads? No idea. It might even work correctly.
281
283 Please report any bugs or feature requests directly to the author.
284
286 Eirik Berg Hanssen, "<ebhanssen@allverden.no>"
287
289 Copyright 2006-2008 Eirik Berg Hanssen, All Rights Reserved.
290 This program is free software; you can redistribute it and/or modify it
292 under the same terms as Perl itself.
293perl v5.12.3 2011-05-06 Test::Trap(3)