1Test::Fatal(3) User Contributed Perl Documentation Test::Fatal(3)
2
6 Test::Fatal - incredibly simple helpers for testing code with
7 exceptions
8
10 version 0.017
11
13 use Test::More;
14 use Test::Fatal;
15 use System::Under::Test qw(might_die);
17 is(
19 exception { might_die; },
20 undef,
21 "the code lived",
22 );
23 like(
25 exception { might_die; },
26 qr/turns out it died/,
27 "the code died as expected",
28 );
29 isa_ok(
31 exception { might_die; },
32 'Exception::Whatever',
33 'the thrown exception',
34 );
35
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 It exports one routine by default: "exception".
42 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
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 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
59 exception
60 my $exception = exception { ... };
61 "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 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 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 "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 Achtung! This is not a great idea:
85 sub exception_like(&$;$) {
87 my ($code, $pattern, $name) = @_;
88 like( &exception($code), $pattern, $name );
89 }
90 exception_like(sub { }, qr/foo/, 'foo appears in the exception');
92 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 like( exception { ... }, qr/foo/, 'foo appears in the exception' );
99 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 sub exception_like(&$) {
105 my ($code, $args) = @_;
106 my ($pattern, $name) = @$args;
107 like( &exception($code), $pattern, $name );
108 }
109 exception_like(sub { }, [ qr/foo/, 'foo appears in the exception' ] );
111 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 Achtung: One final bad idea:
123 isnt( exception { ... }, undef, "my code died!");
125 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 success
135 try {
136 should_live;
137 } catch {
138 fail("boo, we died");
139 } success {
140 pass("hooray, we lived");
141 };
142 "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 Although almost any needed exception tests can be performed with
148 "exception", success blocks may sometimes help organize complex
149 testing.
150 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 RJBS does not suggest using this except as a convenience while porting
159 tests to use Test::Fatal's "exception" routine.
160 use Test::More tests => 2;
162 use Test::Fatal qw(dies_ok lives_ok);
163 dies_ok { die "I failed" } 'code that fails';
165 lives_ok { return "I'm still alive" } 'code that does not fail';
167
169 Ricardo Signes <cpan@semiotic.systems>
170
172 • David Golden <dagolden@cpan.org>
173 • Graham Knop <haarg@haarg.org>
175 • Jesse Luehrs <doy@tozt.net>
177 • Joel Bernstein <joel@fysh.org>
179 • Karen Etheridge <ether@cpan.org>
181 • Ricardo Signes <rjbs@semiotic.systems>
183
185 This software is copyright (c) 2010 by Ricardo Signes.
186 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.
189perl v5.38.0 2023-07-21 Test::Fatal(3)