NAME
Test::Trap - Trap exit codes, exceptions, output, etc.
VERSION
Version 0.0.16
SYNOPSIS
use Test::More;
use Test::Trap qw( trap $trap );
my @r = trap { some_code(@some_parameters) };
is ( $trap->exit, 1, 'Expecting &some_code to exit with 1' );
is ( $trap->stdout, '', 'Expecting no STDOUT' );
like ( $trap->stderr, qr/^Bad parameters; exiting\b/, 'Expecting warnings.' );DESCRIPTION
Primarily (but not exclusively) for use in test scripts: A block eval on steroids, configurable and extensible, but by default trapping (Perl) STDOUT, STDERR, warnings, exceptions, would-be exit codes, and return values from boxed blocks of test code.
The values collected by the latest trap can then be queried or tested through a a special result object.
EXPORT
A function and a scalar may be exported by any name. The function (by default named trap) is an analogue to block eval(), and the scalar (by default named $trap) is the corresponding analogue to $@.
Optionally, you may specify the default layers for the exported trap. Layers may be specified by name, with a colon sigil. Multiple layers may be given in a list, or just stringed together like :flow:stderr:warn.
(For the advanced user, you may also specify anonymous layer implementations -- i.e. an appropriate subroutine.)
See below for a list of the built-in layers, all of which are enabled by default. Note, finally, that the ordering of the layers matter: The :raw layer is always on the bottom (anything underneath it is ignored), and any other "flow control" layers used should be right down there with it.
FUNCTION
trap BLOCK
This function may be exported by any name, but defaults to trap.
Traps exceptions like block eval, but (by default) also traps exits and exit codes, returns and return values, context, and (Perl) STDOUT, STDERR, and warnings, All information trapped can be queried by way of the status object, which is by default exported as $trap, but can be exported by any name.
TRAP LAYERS
It is possible to register more (see Test::Trap::Builder), but the following layers are pre-defined by this module:
:raw
The terminating layer, at which the processing of the layers stops, and the actual call to the user code is performed. On success, it collects the return value(s) in the appropriate context. Pushing the :raw layer on a trap will for most purposes remove all layers below.
:die
The layer emulating block eval, capturing normal exceptions.
:exit
The third "flow control" layer, capturing exit codes if anything used in the dynamic scope of the trap calls CORE::GLOBAL::exit(). (See CAVEATS below for more.)
:flow
A pseudo-layer shortcut for :raw:die:exit. Since this includes :raw, pushing :flow on a trap will remove all layers below.
:stdout, :stderr
Layers trapping Perl output on STDOUT and STDERR, respectively.
:warn
A layer trapping warnings, with additionally tee: If STDERR is open, it will also print the warnings there. (This output may be trapped by the :stderr layer, be it above or below the :warn layer.)
:default
A pseudo-layer short-cut for :raw:die:exit:stdout:stderr:warn. Since this includes :raw, pushing :default on a trap will remove all layers below. The other interesting property of :default is that it is what every trap starts with: In order not to include any of the six layers that make up :default, you need to push a terminating layer (such as :raw or :flow) on the trap.
RESULT ACCESSORS
The following methods may be called on the result objects after any trap has been sprung, and access the cooked results of the run.
Any property will be undef if not actually trapped -- whether because there is no layer to trap them or because flow control passed them by. (If there is an active and successful trap layer, empty strings and empty arrays trapped will of course be defined.)
leaveby
Returns a string indicating how the trap terminated: return, die, or exit.
die
Returns the exception, if the latest trap threw one.
exit
Returns the exit code, if the latest trap tried to exit.
return
Returns an arrayref of return values, if the latest trap returned.
stdout, stderr
Returns the captured output on the respective file handles.
warn
Returns an arrayref of warnings from the latest trap.
wantarray
Returns the context in which the latest trap was called.
list, scalar, void
True if the latest trap was called in the indicated context.
RESULT TESTS
For each accessor, a number of convenient standard test methods are also availible. By default, these are a few standard tests from Test::More, plus the nok test, being a negated ok test. All for convenience:
- ACCESSOR_ok [INDEX,] TEST_NAME
- ACCESSOR_nok [INDEX,] TEST_NAME
- ACCESSOR_is [INDEX,] SCALAR, TEST_NAME
- ACCESSOR_isnt [INDEX,] SCALAR, TEST_NAME
- ACCESSOR_like [INDEX,] REGEX, TEST_NAME
- ACCESSOR_unlike [INDEX,] REGEX, TEST_NAME
- ACCESSOR_is_deeply STRUCTURE, TEST_NAME
INDEX is not optional: It is required for array accessors (like return and warn), and disallowed for scalar accessors. Note that the is_deeply test does not accept an index. Even for array accessors, it operates on the entire array.
For convenience, again, a flow control ACCESSOR (return, die, exit) will first test whether the trap was left by way of the flow control mechanism in question.
did_die, did_exit, did_return
Conveniences: Tests whether the trap was left by way of the flow control mechanism in question. Much like leaveby_is('die') etc, but with better diagnostics.
quiet
Convenience: Passes if zero-length output was trapped on both STDOUT and STDERR, and generate better diagnostics otherwise.
CAVEATS
This module must be loaded before any code containing exit()s to be trapped is compiled. Any exit() already compiled won't be trappable, and will terminate the program anyway.
This module overrides &CORE::GLOBAL::exit, so may not work correctly (or even at all) in the presence of other code overriding &CORE::GLOBAL::exit. More precisely: This module installs its own exit() on entry of the block, and restores the previous one, if any, only upon leaving the block.
If you use fork() in the dynamic scope of a trap, beware that the (default) :exit layer of that trap does not trap exit() in the children, but passes them to the outer handler. If you think about it, this is what you are likely to want it to do in most cases.
Note that the (default) :exit layer only traps &CORE::GLOBAL::exit calls (and bare exit() calls that compile to that). It makes no attempt to trap CORE::exit(), POSIX::_exit(), exec(), nor segfault. Nor does it attempt to trap anything else that might terminate the program. The trap is a block eval on steroids -- not the last block eval of Krypton!
This module traps warnings using $SIG{__WARN__}, so may not work correctly (or even at all) in the presence of other code setting this handler. More precisely: This module installs its own __WARN__ handler on entry of the block, and restores the previous one, if any, only upon leaving the block.
The (default) :stdout and :stderr handlers use in-memory files, and so will not (indeed cannot) trap output from forked-off processes -- including system() calls.
Threads? No idea. It might even work correctly.
BUGS
Please report any bugs or feature requests directly to the author.
AUTHOR
Eirik Berg Hanssen, <ebhanssen@allverden.no>
COPYRIGHT & LICENSE
Copyright 2006 Eirik Berg Hanssen, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.