view release on metacpan or  search on metacpan

local/lib/perl5/Test/Trap.pm  view on Meta::CPAN

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.' );

=head2 :output(a;b;c)

A (non-default, non-trapping) layer that sets the default capture
strategy for any output trapping (C<:stdout>, C<: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 L</"CAPTURE STRATEGIES">.

=head1 CAPTURE STRATEGIES

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

=head2 tempfile

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

=head2 tempfile-preserve

A variant of the capture strategy provided by
L<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.

=head2 systemsafe

A capture strategy provided by L<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.

=head2 systemsafe-preserve

A variant of the capture strategy provided by
L<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.

=head2 perlio

A capture strategy provided by L<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.

=head1 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:

=head2 leaveby

A string indicating how the trap terminated: C<return>, C<die>, or
C<exit>.

=head2 die

The exception, if the latest trap threw one.

=head2 exit

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

=head2 return [INDEX ...]

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

=over

=item

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