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.016
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
43       Achtung!  "exception" intentionally does not manipulate the call stack.
44       User-written test functions that use "exception" must be careful to
45       avoid false positives if exceptions use stack traces that show
46       arguments.  For a more magical approach involving globally overriding
47       "caller", see Test::Exception.
48

FUNCTIONS

50   exception
51         my $exception = exception { ... };
52
53       "exception" takes a bare block of code and returns the exception thrown
54       by that block.  If no exception was thrown, it returns undef.
55
56       Achtung!  If the block results in a false exception, such as 0 or the
57       empty string, Test::Fatal itself will die.  Since either of these cases
58       indicates a serious problem with the system under testing, this
59       behavior is considered a feature.  If you must test for these
60       conditions, you should use Try::Tiny's try/catch mechanism.  (Try::Tiny
61       is the underlying exception handling system of Test::Fatal.)
62
63       Note that there is no TAP assert being performed.  In other words, no
64       "ok" or "not ok" line is emitted.  It's up to you to use the rest of
65       "exception" in an existing test like "ok", "isa_ok", "is", et cetera.
66       Or you may wish to use the "dies_ok" and "lives_ok" wrappers, which do
67       provide TAP output.
68
69       "exception" does not alter the stack presented to the called block,
70       meaning that if the exception returned has a stack trace, it will
71       include some frames between the code calling "exception" and the thing
72       throwing the exception.  This is considered a feature because it avoids
73       the occasionally twitchy "Sub::Uplevel" mechanism.
74
75       Achtung!  This is not a great idea:
76
77         sub exception_like(&$;$) {
78             my ($code, $pattern, $name) = @_;
79             like( &exception($code), $pattern, $name );
80         }
81
82         exception_like(sub { }, qr/foo/, 'foo appears in the exception');
83
84       If the code in the "..." is going to throw a stack trace with the
85       arguments to each subroutine in its call stack (for example via
86       "Carp::confess", the test name, "foo appears in the exception" will
87       itself be matched by the regex.  Instead, write this:
88
89         like( exception { ... }, qr/foo/, 'foo appears in the exception' );
90
91       If you really want a test function that passes the test name, wrap the
92       arguments in an array reference to hide the literal text from a stack
93       trace:
94
95         sub exception_like(&$) {
96             my ($code, $args) = @_;
97             my ($pattern, $name) = @$args;
98             like( &exception($code), $pattern, $name );
99         }
100
101         exception_like(sub { }, [ qr/foo/, 'foo appears in the exception' ] );
102
103       To aid in avoiding the problem where the pattern is seen in the
104       exception because of the call stack, $Carp::MAxArgNums is locally set
105       to -1 when the code block is called.  If you really don't want that,
106       set it back to whatever value you like at the beginning of the code
107       block.  Obviously, this solution doens't affect all possible ways that
108       args of subroutines in the call stack might taint the test.  The
109       intention here is to prevent some false passes from people who didn't
110       read the documentation.  Your punishment for reading it is that you
111       must consider whether to do anything about this.
112
113       Achtung: One final bad idea:
114
115         isnt( exception { ... }, undef, "my code died!");
116
117       It's true that this tests that your code died, but you should really
118       test that it died for the right reason.  For example, if you make an
119       unrelated mistake in the block, like using the wrong dereference, your
120       test will pass even though the code to be tested isn't really run at
121       all.  If you're expecting an inspectable exception with an identifier
122       or class, test that.  If you're expecting a string exception, consider
123       using "like".
124
125   success
126         try {
127           should_live;
128         } catch {
129           fail("boo, we died");
130         } success {
131           pass("hooray, we lived");
132         };
133
134       "success", exported only by request, is a Try::Tiny helper with
135       semantics identical to "finally", but the body of the block will only
136       be run if the "try" block ran without error.
137
138       Although almost any needed exception tests can be performed with
139       "exception", success blocks may sometimes help organize complex
140       testing.
141
142   dies_ok
143   lives_ok
144       Exported only by request, these two functions run a given block of
145       code, and provide TAP output indicating if it did, or did not throw an
146       exception.  These provide an easy upgrade path for replacing existing
147       unit tests based on "Test::Exception".
148
149       RJBS does not suggest using this except as a convenience while porting
150       tests to use Test::Fatal's "exception" routine.
151
152         use Test::More tests => 2;
153         use Test::Fatal qw(dies_ok lives_ok);
154
155         dies_ok { die "I failed" } 'code that fails';
156
157         lives_ok { return "I'm still alive" } 'code that does not fail';
158

AUTHOR

160       Ricardo Signes <rjbs@cpan.org>
161

CONTRIBUTORS

163       •   David Golden <dagolden@cpan.org>
164
165       •   Graham Knop <haarg@haarg.org>
166
167       •   Jesse Luehrs <doy@tozt.net>
168
169       •   Joel Bernstein <joel@fysh.org>
170
171       •   Karen Etheridge <ether@cpan.org>
172
174       This software is copyright (c) 2010 by Ricardo Signes.
175
176       This is free software; you can redistribute it and/or modify it under
177       the same terms as the Perl 5 programming language system itself.
178
179
180
181perl v5.36.0                      2022-07-22                    Test::Fatal(3)
Impressum