Provided by: libtest-trap-perl_0.3.5-1_all bug

NAME

       Test::Trap - Trap exit codes, exceptions, output, etc.

VERSION

       Version 0.3.5

SYNOPSIS

         use Test::More;
         use Test::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 special
       trap 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 layers of 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, most 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".

       By default, traps exceptions (like block eval), but also exits and exit codes, returns and
       return values, context, and (Perl) output on STDOUT or STDERR, and warnings.  All
       information trapped can be queried through the trap object, which is by default exported
       as $trap, but can be exported by any name.

       The value returned from "trap" mimics that returned from "eval":  If the BLOCK would die
       or exit, it returns an undefined value in scalar context or an empty list in list context;
       otherwise it returns whatever the BLOCK would return in the given context (also available
       as the trapped return values).

TRAP LAYERS

       Exactly what the "trap" traps depends on the layers of the trap.  It is possible to
       register more (see Test::Trap::Builder), but the following layers are pre-defined by this
       module:

   :raw
       The only built-in 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, trapping 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 shortcut for :raw:die:exit (effectively pushing all three layers on the trap).  Since
       this includes :raw, it is also terminating:  Pushing :flow on a trap will effectively
       remove all layers below.

   :stdout, :stderr
       Layers trapping Perl output on STDOUT and STDERR, respectively.

   :stdout(perlio), :stderr(perlio)
       As above, but specifying a capture strategy using PerlIO::scalar.  If this strategy is not
       available (typically if PerlIO is not), this is an error.  See "CAPTURE STRATEGIES".

   :stdout(tempfile), :stderr(tempfile)
       As above, but specifying a capture strategy using File::Temp.  Note that this is the
       default strategy, unless the ":output()" layer is used to set another default.  See
       "CAPTURE STRATEGIES".

   :stdout(a;b;c), :stderr(a,b,c)
       (Either syntax, commas or semicolons, is permitted, as is any number of names in the
       list.)  As above, but specifying the capture strategy by the first existing name among a,
       b, and c.  If no such strategy is found, this is an error.  See "CAPTURE STRATEGIES".

   :warn
       A layer trapping warnings, with additional 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 short-cut for :raw:die:exit:stdout:stderr:warn (effectively pushing all six layers on
       the trap).  Since this includes :raw, it is also terminating:  Pushing :default on a trap
       will effectively remove all layers below.

       The other interesting property of :default is that it is what every trap starts with:  In
       order not to include the six layers that make up :default, you need to push a terminating
       layer (such as :raw or :flow) on the trap.

   :on_fail(m)
       A (non-default, non-trapping) layer that installs a callback method (by name) m to be run
       on test failures.  To run the "diag_all" method every time a test fails:

         use Test::Trap qw/ :on_fail(diag_all) /;

   :void, :scalar, :list
       These (non-default, non-trapping) layers will cause the trapped user code to be run in
       void, scalar, or list context, respectively.  (By default, the trap will propagate
       context, that is, it will run the code in whatever context the trap itself is in.)

       If more than one of these layers are pushed on the trap, the deepest (that is, leftmost)
       takes precedence:

         use Test::Trap qw/ :scalar:void:list /;
         trap { 42, 13 };
         $trap->return_is_deeply( [ 13 ], 'Scalar comma.' );

   :output(a;b;c)
       A (non-default, non-trapping) layer that sets the default capture strategy for any output
       trapping (":stdout", ":stderr", or other similarly defined) layers below iton the trap.

         use Test::Trap qw/ :output(systemsafe) /;
         trap { system echo => 'Hello Unix!' }; # trapped!

         use Test::Trap qw/ :flow:stderr:output(systemsafe):stdout /;
         trap { system echo => 'Hello Unix!' }; # *not* trapped!
         trap { system q/ echo 'Hello Unix!' >&2 / }; # trapped!

       See "CAPTURE STRATEGIES".

CAPTURE STRATEGIES

       How output is trapped, depends on the capture strategy used.  It is possible to register
       more (see Test::Trap::Builder), but the following strategies are pre-defined by this
       module:

   tempfile
       The default capture strategy, provided by Test::Trap::Builder::TempFile, in which output
       is temporarily redirected to (and read back from) a tempfile.

   tempfile-preserve
       A variant of the capture strategy provided by Test::Trap::Builder::TempFile, in which the
       handles used to write to and read from the tempfile are both binmoded with the same perlio
       layers as the trapped output handle originally had.

       Caveat emptor: If the handle has perlio custom layers, they may (or may not) fail to apply
       to the tempfile read and write handles.

   systemsafe
       A capture strategy provided by Test::Trap::Builder::SystemSafe, like the default strategy,
       except it outputs on file handles with the same file descriptors as the trapped output
       handle originally had, and so can be used to trap output from forked-off processes,
       including system().

       This strategy may be "safe" in relation to forked-off processes, but it is fragile.  For
       one, it only works with handles that have "real" file descriptors.  For another, it
       depends on the original file descriptors being available after closing.  (If signal
       handlers or threads open files, they may well not be.)  And it may fail in other ways.
       But in relation to forked-off processes, the other pre-defined strategies will silently
       fail to trap, as will similarly simple strategies.  This one, when not crashing, will trap
       that output.

   systemsafe-preserve
       A variant of the capture strategy provided by Test::Trap::Builder::SystemSafe, in which
       the handles used to write to and read from the tempfile are both binmoded with the same
       perlio layers as the trapped output handle originally had.

       Caveat emptor: If the handle has perlio custom layers, they may (or may not) fail to apply
       to the tempfile read and write handles.

   perlio
       A capture strategy provided by Test::Trap::Builder::PerlIO, in which output is temporarily
       redirected to an in-memory file via PerlIO::scalar.

       If PerlIO::scalar is not available, neither is this strategy.

RESULT ACCESSORS

       The following methods may be called on the trap objects after any trap has been sprung,
       and access the outcome 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.)

       When properties are set, their values will be as follows:

   leaveby
       A string indicating how the trap terminated: "return", "die", or "exit".

   die
       The exception, if the latest trap threw one.

   exit
       The exit code, if the latest trap tried to exit (by way of the trap's own
       &CORE::GLOBAL::exit only; see "CAVEATS").

   return [INDEX ...]
       Returns undef if the latest trap did not terminate with a return; otherwise returns three
       different views of the return array:

       •   if no INDEX is passed, returns a reference to the array (NB! an empty array of indices
           qualifies as "no index")

       •   if called with at least one INDEX in scalar context, returns the array element indexed
           by the first INDEX (ignoring the rest)

       •   if called with at least one INDEX in list context, returns the slice of the array by
           these indices

       Note: The array will hold but a single value if the trap was sprung in scalar context, and
       will be empty if it was in void context.

   stdout, stderr
       The captured output on the respective file handles.

   warn [INDEX]
       Returns undef if the latest trap had no warning-trapping layer; otherwise returns three
       different views of the warn array:

       •   if no INDEX is passed, returns a reference to the array (NB! an empty array of indices
           qualifies as "no index")

       •   if called with at least one INDEX in scalar context, returns the array element indexed
           by the first INDEX (ignoring the rest)

       •   if called with at least one INDEX in list context, returns the slice of the array by
           these indices

   wantarray
       The context in which the latest code trapped was called.  (By default a propagated
       context, but layers can override this.)

   list, scalar, void
       True if the latest code trapped was called in the indicated context.  (By default the code
       will be called in a propagated context, but layers can override this.)

RESULT TESTS

       For each accessor, a number of convenient standard test methods are also available.  By
       default, these are a few standard tests from Test::More, plus the "nok" test (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_isa_ok    [INDEX,] SCALAR, INVOCANT_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 and clarity, tests against a flow control ACCESSOR ("return", "die",
       "exit", or any you define yourself) will first test whether the trap was left by way of
       the flow control mechanism in question, and fail with appropriate diagnostics otherwise.

   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 and (run-time)
       spell checking.

   quiet
       Convenience: Passes if zero-length output was trapped on both STDOUT and STDERR, and
       generate better diagnostics otherwise.

UTILITIES

   diag_all
       Prints a diagnostic message (as per "diag" in Test::More) consisting of a dump (in Perl
       code, as per Data::Dump) of the trap object.

   diag_all_once
       As "diag_all", except if this instance of the trap object has already been
       diag_all_once'd, the diagnostic message will instead consist of the string "(as above)".

       This could be useful with the "on_fail" layer:

         use Test::Trap qw/ :on_fail(diag_all_once) /;

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(), untrapped exceptions from die(), 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 will not trap output from 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@cpan.org>"

COPYRIGHT & LICENSE

       Copyright 2006-2014 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.