-
-
09 Aug 2020 02:01:20 UTC
- Distribution: Test-Fatal
- Module version: 0.016
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (0)
- Testers (3911 / 2 / 0)
- Kwalitee
Bus factor: 1- 89.52% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (20.75KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
NAME
Test::Fatal - incredibly simple helpers for testing code with exceptions
VERSION
version 0.016
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 useexception
must be careful to avoid false positives if exceptions use stack traces that show arguments. For a more magical approach involving globally overridingcaller
, see Test::Exception.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 likeok
,isa_ok
,is
, et cetera. Or you may wish to use thedies_ok
andlives_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 callingexception
and the thing throwing the exception. This is considered a feature because it avoids the occasionally twitchySub::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 viaCarp::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 tofinally
, but the body of the block will only be run if thetry
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 <rjbs@cpan.org>
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>
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.
Module Install Instructions
To install Test::Fatal, copy and paste the appropriate command in to your terminal.
cpanm Test::Fatal
perl -MCPAN -e shell install Test::Fatal
For more information on module installation, please visit the detailed CPAN module installation guide.