Test::Exception(3pm)

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

NAME

6       Test::Exception - Test exception based code
7

SYNOPSIS

9         use Test::More tests => 5;
10         use Test::Exception;
11
12         # or if you don't need Test::More
13
14         use Test::Exception tests => 5;
15
16         # then...
17
18         # Check that the stringified exception matches given regex
19         throws_ok { $foo->method } qr/division by zero/, 'zero caught okay';
20
21         # Check an exception of the given class (or subclass) is thrown
22         throws_ok { $foo->method } 'Error::Simple', 'simple error thrown';
23
24         # all Test::Exceptions subroutines are guaranteed to preserve the state
25         # of $@ so you can do things like this after throws_ok and dies_ok
26         like $@, 'what the stringified exception should look like';
27
28         # Check that something died - we do not care why
29         dies_ok { $foo->method } 'expecting to die';
30
31         # Check that something did not die
32         lives_ok { $foo->method } 'expecting to live';
33
34         # Check that a test runs without an exception
35         lives_and { is $foo->method, 42 } 'method is 42';
36
37         # or if you don't like prototyped functions
38
39         throws_ok( sub { $foo->method }, qr/division by zero/,
40             'zero caught okay' );
41         throws_ok( sub { $foo->method }, 'Error::Simple',
42             'simple error thrown' );
43         dies_ok( sub { $foo->method }, 'expecting to die' );
44         lives_ok( sub { $foo->method }, 'expecting to live' );
45         lives_and( sub { is $foo->method, 42 }, 'method is 42' );
46

DESCRIPTION

48       This module provides a few convenience methods for testing exception
49       based code. It is built with Test::Builder and plays happily with
50       Test::More and friends.
51
52       If you are not already familiar with Test::More now would be the time
53       to go take a look.
54
55       You can specify the test plan when you "use Test::Exception" in the
56       same way as "use Test::More".  See Test::More for details.
57
58       NOTE: Test::Exception only checks for exceptions. It will ignore other
59       methods of stopping program execution - including exit(). If you have
60       an exit() in evalled code Test::Exception will not catch this with any
61       of its testing functions.
62
63       throws_ok
64           Tests to see that a specific exception is thrown. throws_ok() has
65           two forms:
66
67             throws_ok BLOCK REGEX, TEST_DESCRIPTION
68             throws_ok BLOCK CLASS, TEST_DESCRIPTION
69
70           In the first form the test passes if the stringified exception
71           matches the give regular expression. For example:
72
73               throws_ok { read_file( 'unreadable' ) } qr/No file/, 'no file';
74
75           If your perl does not support "qr//" you can also pass a regex-like
76           string, for example:
77
78               throws_ok { read_file( 'unreadable' ) } '/No file/', 'no file';
79
80           The second form of throws_ok() test passes if the exception is of
81           the same class as the one supplied, or a subclass of that class.
82           For example:
83
84               throws_ok { $foo->bar } "Error::Simple", 'simple error';
85
86           Will only pass if the "bar" method throws an Error::Simple
87           exception, or a subclass of an Error::Simple exception.
88
89           You can get the same effect by passing an instance of the exception
90           you want to look for. The following is equivalent to the previous
91           example:
92
93               my $SIMPLE = Error::Simple->new;
94               throws_ok { $foo->bar } $SIMPLE, 'simple error';
95
96           Should a throws_ok() test fail it produces appropriate diagnostic
97           messages. For example:
98
99               not ok 3 - simple error
100               #     Failed test (test.t at line 48)
101               # expecting: Error::Simple exception
102               # found: normal exit
103
104           Like all other Test::Exception functions you can avoid prototypes
105           by passing a subroutine explicitly:
106
107               throws_ok( sub {$foo->bar}, "Error::Simple", 'simple error' );
108
109           A true value is returned if the test succeeds, false otherwise. On
110           exit $@ is guaranteed to be the cause of death (if any).
111
112           A description of the exception being checked is used if no optional
113           test description is passed.
114
115       dies_ok
116           Checks that a piece of code dies, rather than returning normally.
117           For example:
118
119               sub div {
120                   my ( $a, $b ) = @_;
121                   return $a / $b;
122               };
123
124               dies_ok { div( 1, 0 ) } 'divide by zero detected';
125
126               # or if you don't like prototypes
127               dies_ok( sub { div( 1, 0 ) }, 'divide by zero detected' );
128
129           A true value is returned if the test succeeds, false otherwise. On
130           exit $@ is guaranteed to be the cause of death (if any).
131
132           Remember: This test will pass if the code dies for any reason. If
133           you care about the reason it might be more sensible to write a more
134           specific test using throws_ok().
135
136           The test description is optional, but recommended.
137
138       lives_ok
139           Checks that a piece of code doesn't die. This allows your test
140           script to continue, rather than aborting if you get an unexpected
141           exception. For example:
142
143               sub read_file {
144                   my $file = shift;
145                   local $/;
146                   open my $fh, '<', $file or die "open failed ($!)\n";
147                   $file = <FILE>;
148                   return $file;
149               };
150
151               my $file;
152               lives_ok { $file = read_file('test.txt') } 'file read';
153
154               # or if you don't like prototypes
155               lives_ok( sub { $file = read_file('test.txt') }, 'file read' );
156
157           Should a lives_ok() test fail it produces appropriate diagnostic
158           messages. For example:
159
160               not ok 1 - file read
161               #     Failed test (test.t at line 15)
162               # died: open failed (No such file or directory)
163
164           A true value is returned if the test succeeds, false otherwise. On
165           exit $@ is guaranteed to be the cause of death (if any).
166
167           The test description is optional, but recommended.
168
169       lives_and
170           Run a test that may throw an exception. For example, instead of
171           doing:
172
173             my $file;
174             lives_ok { $file = read_file('answer.txt') } 'read_file worked';
175             is $file, "42", 'answer was 42';
176
177           You can use lives_and() like this:
178
179             lives_and { is read_file('answer.txt'), "42" } 'answer is 42';
180             # or if you don't like prototypes
181             lives_and(sub {is read_file('answer.txt'), "42"}, 'answer is 42');
182
183           Which is the same as doing
184
185             is read_file('answer.txt'), "42\n", 'answer is 42';
186
187           unless "read_file('answer.txt')" dies, in which case you get the
188           same kind of error as lives_ok()
189
190             not ok 1 - answer is 42
191             #     Failed test (test.t at line 15)
192             # died: open failed (No such file or directory)
193
194           A true value is returned if the test succeeds, false otherwise. On
195           exit $@ is guaranteed to be the cause of death (if any).
196
197           The test description is optional, but recommended.
198

SKIPPING TEST::EXCEPTION TESTS

200       Sometimes we want to use Test::Exception tests in a test suite, but
201       don't want to force the user to have Test::Exception installed. One way
202       to do this is to skip the tests if Test::Exception is absent. You can
203       do this with code something like this:
204
205         use strict;
206         use warnings;
207         use Test::More;
208
209         BEGIN {
210             eval "use Test::Exception";
211             plan skip_all => "Test::Exception needed" if $@;
212         }
213
214         plan tests => 2;
215         # ... tests that need Test::Exception ...
216
217       Note that we load Test::Exception in a "BEGIN" block ensuring that the
218       subroutine prototypes are in place before the rest of the test script
219       is compiled.
220

BUGS

222       There are some edge cases in Perl's exception handling where
223       Test::Exception will miss exceptions thrown in DESTROY blocks. See the
224       RT bug <http://rt.cpan.org/Ticket/Display.html?id=24678> for details,
225       along with the t/edge-cases.t in the distribution test suite. These
226       will be addressed in a future Test::Exception release.
227
228       If you find any more bugs please let me know by e-mail, or report the
229       problem with <http://rt.cpan.org/>.
230

COMMUNITY

232       perl-qa
233           If you are interested in testing using Perl I recommend you visit
234           <http://qa.perl.org/> and join the excellent perl-qa mailing list.
235           See <http://lists.perl.org/showlist.cgi?name=perl-qa> for details
236           on how to subscribe.
237
238       perlmonks
239           You can find users of Test::Exception, including the module author,
240           on  <http://www.perlmonks.org/>. Feel free to ask questions on
241           Test::Exception there.
242
243       CPAN::Forum
244           The CPAN Forum is a web forum for discussing Perl's CPAN modules.
245           The Test::Exception forum can be found at
246           <http://www.cpanforum.com/dist/Test-Exception>.
247
248       AnnoCPAN
249           AnnoCPAN is a web site that allows community annotations of Perl
250           module documentation. The Test::Exception annotations can be found
251           at <http://annocpan.org/~ADIE/Test-Exception/>.
252

TO DO

254       If you think this module should do something that it doesn't (or does
255       something that it shouldn't) please let me know.
256
257       You can see my current to do list at
258       <http://adrianh.tadalist.com/lists/public/15421>, with an RSS feed of
259       changes at <http://adrianh.tadalist.com/lists/feed_public/15421>.
260

ACKNOWLEDGMENTS

262       Thanks to chromatic and Michael G Schwern for the excellent
263       Test::Builder, without which this module wouldn't be possible.
264
265       Thanks to Adam Kennedy, Andy Lester, Aristotle Pagaltzis, Ben Prew,
266       Cees Hek, Chris Dolan, chromatic, Curt Sampson, David Cantrell, David
267       Golden, David Wheeler, Janek Schleicher, Jim Keenan, Jos I. Boumans,
268       Joshua ben Jore, Jost Krieger, Mark Fowler, Michael G Schwern, Nadim
269       Khemir, Paul McCann, Perrin Harkins, Peter Scott, Rob Muhlestein Scott
270       R. Godin, Steve Purkis, Steve, Tim Bunce, and various anonymous folk
271       for comments, suggestions, bug reports and patches.
272

AUTHOR

274       Adrian Howard <adrianh@quietstars.com>
275
276       If you can spare the time, please drop me a line if you find this
277       module useful.
278

LICENCE

299       Copyright 2002-2007 Adrian Howard, All Rights Reserved.
300
301       This program is free software; you can redistribute it and/or modify it
302       under the same terms as Perl itself.
303
304
305
306perl v5.10.1                      2010-11-12                Test::Exception(3)