WWWWWW

Current Directory: /usr/local/share/man/man3
Viewing File: /usr/local/share/man/man3/Test::Fatal.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Fatal 3"
.TH Test::Fatal 3 "2022-12-31" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Fatal \- incredibly simple helpers for testing code with exceptions
.SH "VERSION"
.IX Header "VERSION"
version 0.017
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Test::More;
\&  use Test::Fatal;
\&
\&  use System::Under::Test qw(might_die);
\&
\&  is(
\&    exception { might_die; },
\&    undef,
\&    "the code lived",
\&  );
\&
\&  like(
\&    exception { might_die; },
\&    qr/turns out it died/,
\&    "the code died as expected",
\&  );
\&
\&  isa_ok(
\&    exception { might_die; },
\&    \*(AqException::Whatever\*(Aq,
\&    \*(Aqthe thrown exception\*(Aq,
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Test::Fatal is an alternative to the popular Test::Exception.  It does much
less, but should allow greater flexibility in testing exception-throwing code
with about the same amount of typing.
.PP
It exports one routine by default: \f(CW\*(C`exception\*(C'\fR.
.PP
\&\fBAchtung!\fR  \f(CW\*(C`exception\*(C'\fR intentionally does not manipulate the call stack.
User-written test functions that use \f(CW\*(C`exception\*(C'\fR must be careful to avoid
false positives if exceptions use stack traces that show arguments.  For a more
magical approach involving globally overriding \f(CW\*(C`caller\*(C'\fR, see
Test::Exception.
.SH "PERL VERSION"
.IX Header "PERL VERSION"
This library should run on perls released even a long time ago.  It should work
on any version of perl released in the last five years.
.PP
Although it may work on older versions of perl, no guarantee is made that the
minimum required version will not be increased.  The version may be increased
for any reason, and there is no promise that patches will be accepted to lower
the minimum required perl.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "exception"
.IX Subsection "exception"
.Vb 1
\&  my $exception = exception { ... };
.Ve
.PP
\&\f(CW\*(C`exception\*(C'\fR takes a bare block of code and returns the exception thrown by
that block.  If no exception was thrown, it returns undef.
.PP
\&\fBAchtung!\fR  If the block results in a \fIfalse\fR exception, such as 0 or the
empty string, Test::Fatal itself will die.  Since either of these cases
indicates a serious problem with the system under testing, this behavior is
considered a \fIfeature\fR.  If you must test for these conditions, you should use
Try::Tiny's try/catch mechanism.  (Try::Tiny is the underlying exception
handling system of Test::Fatal.)
.PP
Note that there is no \s-1TAP\s0 assert being performed.  In other words, no \*(L"ok\*(R" or
\&\*(L"not ok\*(R" line is emitted.  It's up to you to use the rest of \f(CW\*(C`exception\*(C'\fR in an
existing test like \f(CW\*(C`ok\*(C'\fR, \f(CW\*(C`isa_ok\*(C'\fR, \f(CW\*(C`is\*(C'\fR, et cetera.  Or you may wish to use
the \f(CW\*(C`dies_ok\*(C'\fR and \f(CW\*(C`lives_ok\*(C'\fR wrappers, which do provide \s-1TAP\s0 output.
.PP
\&\f(CW\*(C`exception\*(C'\fR does \fInot\fR alter the stack presented to the called block, meaning
that if the exception returned has a stack trace, it will include some frames
between the code calling \f(CW\*(C`exception\*(C'\fR and the thing throwing the exception.
This is considered a \fIfeature\fR because it avoids the occasionally twitchy
\&\f(CW\*(C`Sub::Uplevel\*(C'\fR mechanism.
.PP
\&\fBAchtung!\fR  This is not a great idea:
.PP
.Vb 4
\&  sub exception_like(&$;$) {
\&      my ($code, $pattern, $name) = @_;
\&      like( &exception($code), $pattern, $name );
\&  }
\&
\&  exception_like(sub { }, qr/foo/, \*(Aqfoo appears in the exception\*(Aq);
.Ve
.PP
If the code in the \f(CW\*(C`...\*(C'\fR is going to throw a stack trace with the arguments to
each subroutine in its call stack (for example via \f(CW\*(C`Carp::confess\*(C'\fR,
the test name, \*(L"foo appears in the exception\*(R" will itself be matched by the
regex.  Instead, write this:
.PP
.Vb 1
\&  like( exception { ... }, qr/foo/, \*(Aqfoo appears in the exception\*(Aq );
.Ve
.PP
If you really want a test function that passes the test name, wrap the
arguments in an array reference to hide the literal text from a stack trace:
.PP
.Vb 5
\&  sub exception_like(&$) {
\&      my ($code, $args) = @_;
\&      my ($pattern, $name) = @$args;
\&      like( &exception($code), $pattern, $name );
\&  }
\&
\&  exception_like(sub { }, [ qr/foo/, \*(Aqfoo appears in the exception\*(Aq ] );
.Ve
.PP
To aid in avoiding the problem where the pattern is seen in the exception
because of the call stack, \f(CW$Carp::MaxArgNums\fR is locally set to \-1 when the
code block is called.  If you really don't want that, set it back to whatever
value you like at the beginning of the code block.  Obviously, this solution
doens't affect all possible ways that args of subroutines in the call stack
might taint the test.  The intention here is to prevent some false passes from
people who didn't read the documentation.  Your punishment for reading it is
that you must consider whether to do anything about this.
.PP
\&\fBAchtung\fR: One final bad idea:
.PP
.Vb 1
\&  isnt( exception { ... }, undef, "my code died!");
.Ve
.PP
It's true that this tests that your code died, but you should really test that
it died \fIfor the right reason\fR.  For example, if you make an unrelated mistake
in the block, like using the wrong dereference, your test will pass even though
the code to be tested isn't really run at all.  If you're expecting an
inspectable exception with an identifier or class, test that.  If you're
expecting a string exception, consider using \f(CW\*(C`like\*(C'\fR.
.SS "success"
.IX Subsection "success"
.Vb 7
\&  try {
\&    should_live;
\&  } catch {
\&    fail("boo, we died");
\&  } success {
\&    pass("hooray, we lived");
\&  };
.Ve
.PP
\&\f(CW\*(C`success\*(C'\fR, exported only by request, is a Try::Tiny helper with semantics
identical to \f(CW\*(C`finally\*(C'\fR, but the body of the block will
only be run if the \f(CW\*(C`try\*(C'\fR block ran without error.
.PP
Although almost any needed exception tests can be performed with \f(CW\*(C`exception\*(C'\fR,
success blocks may sometimes help organize complex testing.
.SS "dies_ok"
.IX Subsection "dies_ok"
.SS "lives_ok"
.IX Subsection "lives_ok"
Exported only by request, these two functions run a given block of code, and
provide \s-1TAP\s0 output indicating if it did, or did not throw an exception.
These provide an easy upgrade path for replacing existing unit tests based on
\&\f(CW\*(C`Test::Exception\*(C'\fR.
.PP
\&\s-1RJBS\s0 does not suggest using this except as a convenience while porting tests to
use Test::Fatal's \f(CW\*(C`exception\*(C'\fR routine.
.PP
.Vb 2
\&  use Test::More tests => 2;
\&  use Test::Fatal qw(dies_ok lives_ok);
\&
\&  dies_ok { die "I failed" } \*(Aqcode that fails\*(Aq;
\&
\&  lives_ok { return "I\*(Aqm still alive" } \*(Aqcode that does not fail\*(Aq;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ricardo Signes <cpan@semiotic.systems>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
David Golden <dagolden@cpan.org>
.IP "\(bu" 4
Graham Knop <haarg@haarg.org>
.IP "\(bu" 4
Jesse Luehrs <doy@tozt.net>
.IP "\(bu" 4
Joel Bernstein <joel@fysh.org>
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Ricardo Signes <rjbs@semiotic.systems>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Ricardo Signes.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
F1l3 Manager
