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.017
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

PERL VERSION

50       This library should run on perls released even a long time ago.  It
51       should work on any version of perl released in the last five years.
52
53       Although it may work on older versions of perl, no guarantee is made
54       that the minimum required version will not be increased.  The version
55       may be increased for any reason, and there is no promise that patches
56       will be accepted to lower the minimum required perl.
57

FUNCTIONS

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

AUTHOR

169       Ricardo Signes <cpan@semiotic.systems>
170

CONTRIBUTORS

172       •   David Golden <dagolden@cpan.org>
173
174       •   Graham Knop <haarg@haarg.org>
175
176       •   Jesse Luehrs <doy@tozt.net>
177
178       •   Joel Bernstein <joel@fysh.org>
179
180       •   Karen Etheridge <ether@cpan.org>
181
182       •   Ricardo Signes <rjbs@semiotic.systems>
183
185       This software is copyright (c) 2010 by Ricardo Signes.
186
187       This is free software; you can redistribute it and/or modify it under
188       the same terms as the Perl 5 programming language system itself.
189
190
191
192perl v5.36.0                      2023-01-20                    Test::Fatal(3)
Impressum