Test::Fatal(3pm) User Contributed Perl Documentation Test::Fatal(3pm)
NAME
Test::Fatal - incredibly simple helpers for testing code with
exceptions
VERSION
version 0.017
SYNOPSIS
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; },
'Exception::Whatever',
'the thrown exception',
);
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.
It exports one routine by default: "exception".
Achtung! "exception" intentionally does not manipulate the call stack.
User-written test functions that use "exception" must be careful to
avoid false positives if exceptions use stack traces that show
arguments. For a more magical approach involving globally overriding
"caller", see Test::Exception.
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.
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.
FUNCTIONS
exception
my $exception = exception { ... };
"exception" takes a bare block of code and returns the exception thrown
by that block. If no exception was thrown, it returns undef.
Achtung! If the block results in a false 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 feature. 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.)
Note that there is no TAP assert being performed. In other words, no
"ok" or "not ok" line is emitted. It's up to you to use the rest of
"exception" in an existing test like "ok", "isa_ok", "is", et cetera.
Or you may wish to use the "dies_ok" and "lives_ok" wrappers, which do
provide TAP output.
"exception" does not 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 "exception" and the thing
throwing the exception. This is considered a feature because it avoids
the occasionally twitchy "Sub::Uplevel" mechanism.
Achtung! This is not a great idea:
sub exception_like(&$;$) {
my ($code, $pattern, $name) = @_;
like( &exception($code), $pattern, $name );
}
exception_like(sub { }, qr/foo/, 'foo appears in the exception');
If the code in the "..." is going to throw a stack trace with the
arguments to each subroutine in its call stack (for example via
"Carp::confess", the test name, "foo appears in the exception" will
itself be matched by the regex. Instead, write this:
like( exception { ... }, qr/foo/, 'foo appears in the exception' );
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:
sub exception_like(&$) {
my ($code, $args) = @_;
my ($pattern, $name) = @$args;
like( &exception($code), $pattern, $name );
}
exception_like(sub { }, [ qr/foo/, 'foo appears in the exception' ] );
To aid in avoiding the problem where the pattern is seen in the
exception because of the call stack, $Carp::MaxArgNums 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.
Achtung: One final bad idea:
isnt( exception { ... }, undef, "my code died!");
It's true that this tests that your code died, but you should really
test that it died for the right reason. 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 "like".
success
try {
should_live;
} catch {
fail("boo, we died");
} success {
pass("hooray, we lived");
};
"success", exported only by request, is a Try::Tiny helper with
semantics identical to "finally", but the body of the block will only
be run if the "try" block ran without error.
Although almost any needed exception tests can be performed with
"exception", success blocks may sometimes help organize complex
testing.
dies_ok
lives_ok
Exported only by request, these two functions run a given block of
code, and provide TAP output indicating if it did, or did not throw an
exception. These provide an easy upgrade path for replacing existing
unit tests based on "Test::Exception".
RJBS does not suggest using this except as a convenience while porting
tests to use Test::Fatal's "exception" routine.
use Test::More tests => 2;
use Test::Fatal qw(dies_ok lives_ok);
dies_ok { die "I failed" } 'code that fails';
lives_ok { return "I'm still alive" } 'code that does not fail';
AUTHOR
Ricardo Signes <cpan@semiotic.systems>
CONTRIBUTORS
• David Golden <dagolden@cpan.org>
• Graham Knop <haarg@haarg.org>
• Jesse Luehrs <doy@tozt.net>
• Joel Bernstein <joel@fysh.org>
• Karen Etheridge <ether@cpan.org>
• Ricardo Signes <rjbs@semiotic.systems>
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.36.0 2023-01-04 Test::Fatal(3pm)
Generated by dwww version 1.15 on Sun Jun 23 04:03:58 CEST 2024.