1Test::Fatal(3)        User Contributed Perl Documentation       Test::Fatal(3)
2
3
4

NAME

6       Test::Fatal - incredibly simple helpers for testing code with
7       exceptions
8

VERSION

10       version 0.014
11

SYNOPSIS

13         use Test::More;
14         use Test::Fatal;
15
16         use System::Under::Test qw(might_die);
17
18         is(
19           exception { might_die; },
20           undef,
21           "the code lived",
22         );
23
24         like(
25           exception { might_die; },
26           qr/turns out it died/,
27           "the code died as expected",
28         );
29
30         isa_ok(
31           exception { might_die; },
32           'Exception::Whatever',
33           'the thrown exception',
34         );
35

DESCRIPTION

37       Test::Fatal is an alternative to the popular Test::Exception.  It does
38       much less, but should allow greater flexibility in testing exception-
39       throwing code with about the same amount of typing.
40
41       It exports one routine by default: "exception".
42

FUNCTIONS

44   exception
45         my $exception = exception { ... };
46
47       "exception" takes a bare block of code and returns the exception thrown
48       by that block.  If no exception was thrown, it returns undef.
49
50       Achtung!  If the block results in a false exception, such as 0 or the
51       empty string, Test::Fatal itself will die.  Since either of these cases
52       indicates a serious problem with the system under testing, this
53       behavior is considered a feature.  If you must test for these
54       conditions, you should use Try::Tiny's try/catch mechanism.  (Try::Tiny
55       is the underlying exception handling system of Test::Fatal.)
56
57       Note that there is no TAP assert being performed.  In other words, no
58       "ok" or "not ok" line is emitted.  It's up to you to use the rest of
59       "exception" in an existing test like "ok", "isa_ok", "is", et cetera.
60       Or you may wish to use the "dies_ok" and "lives_ok" wrappers, which do
61       provide TAP output.
62
63       "exception" does not alter the stack presented to the called block,
64       meaning that if the exception returned has a stack trace, it will
65       include some frames between the code calling "exception" and the thing
66       throwing the exception.  This is considered a feature because it avoids
67       the occasionally twitchy "Sub::Uplevel" mechanism.
68
69       Achtung!  This is not a great idea:
70
71         sub exception_like(&$;$) {
72             my ($code, $pattern, $name) = @_;
73             like( &exception($code), $pattern, $name );
74         }
75
76         exception_like(sub { }, qr/foo/, 'foo appears in the exception');
77
78       If the code in the "..." is going to throw a stack trace with the
79       arguments to each subroutine in its call stack (for example via
80       "Carp::confess", the test name, "foo appears in the exception" will
81       itself be matched by the regex.  Instead, write this:
82
83         like( exception { ... }, qr/foo/, 'foo appears in the exception' );
84
85       Achtung: One final bad idea:
86
87         isnt( exception { ... }, undef, "my code died!");
88
89       It's true that this tests that your code died, but you should really
90       test that it died for the right reason.  For example, if you make an
91       unrelated mistake in the block, like using the wrong dereference, your
92       test will pass even though the code to be tested isn't really run at
93       all.  If you're expecting an inspectable exception with an identifier
94       or class, test that.  If you're expecting a string exception, consider
95       using "like".
96
97   success
98         try {
99           should_live;
100         } catch {
101           fail("boo, we died");
102         } success {
103           pass("hooray, we lived");
104         };
105
106       "success", exported only by request, is a Try::Tiny helper with
107       semantics identical to "finally", but the body of the block will only
108       be run if the "try" block ran without error.
109
110       Although almost any needed exception tests can be performed with
111       "exception", success blocks may sometimes help organize complex
112       testing.
113
114   dies_ok
115   lives_ok
116       Exported only by request, these two functions run a given block of
117       code, and provide TAP output indicating if it did, or did not throw an
118       exception.  These provide an easy upgrade path for replacing existing
119       unit tests based on "Test::Exception".
120
121       RJBS does not suggest using this except as a convenience while porting
122       tests to use Test::Fatal's "exception" routine.
123
124         use Test::More tests => 2;
125         use Test::Fatal qw(dies_ok lives_ok);
126
127         dies_ok { die "I failed" } 'code that fails';
128
129         lives_ok { return "I'm still alive" } 'code that does not fail';
130

AUTHOR

132       Ricardo Signes <rjbs@cpan.org>
133

135       This software is copyright (c) 2010 by Ricardo Signes.
136
137       This is free software; you can redistribute it and/or modify it under
138       the same terms as the Perl 5 programming language system itself.
139
140
141
142perl v5.30.0                      2019-07-26                    Test::Fatal(3)
Impressum