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 something died
19         dies_ok {$foo->method1} 'expecting to die';
20
21         # Check that something did not die
22         lives_ok {$foo->method2} 'expecting to live';
23
24         # Check that the stringified exception matches given regex
25         throws_ok {$foo->method3} qr/division by zero/, 'zero caught okay';
26
27         # Check an exception of the given class (or subclass) is thrown
28         throws_ok {$foo->method4} 'Error::Simple', 'simple error thrown';
29
30         # Check that a test runs without an exception
31         lives_and {is $foo->method, 42} 'method is 42';
32
33         # or if you don't like prototyped functions
34
35         dies_ok( sub { $foo->method1 }, 'expecting to die' );
36         lives_ok( sub {$foo->method2}, 'expecting to live' );
37         throws_ok( sub {$foo->method3}, qr/division by zero/,
38             'zero caught okay' );
39         throws_ok( sub {$foo->method4}, 'Error::Simple',
40             'simple error thrown' );
41         lives_and( sub {is $foo->method, 42}, 'method is 42' );
42

DESCRIPTION

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

BUGS

189       None known at the time of writing.
190
191       If you find any please let me know by e-mail, or report the problem
192       with <http://rt.cpan.org/>.
193

COMMUNITY

195       perl-qa
196
197       If you are interested in testing using Perl I recommend you visit
198       <http://qa.perl.org/> and join the excellent perl-qa mailing list. See
199       <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on how to
200       subscribe.
201
202       perlmonks
203
204       You can find users of Test::Exception, including the module author, on
205       <http://www.perlmonks.org/>. Feel free to ask questions on Test::Excep‐
206       tion there.
207
208       CPAN::Forum
209
210       The CPAN Forum is a web forum for discussing Perl's CPAN modules.   The
211       Test::Exception forum can be found at <http://www.cpanfo‐
212       rum.com/dist/Test-Exception>.
213

TO DO

215       If you think this module should do something that it doesn't (or does
216       something that it shouldn't) please let me know.
217
218       You can see my current to do list at <http://adrianh.tadal‐
219       ist.com/lists/public/15421>, with an RSS feed of changes at
220       <http://adrianh.tadalist.com/lists/feed_public/15421>.
221

ACKNOWLEGEMENTS

223       Thanks to chromatic and Michael G Schwern for the excellent
224       Test::Builder, without which this module wouldn't be possible.
225
226       Thanks to Michael G Schwern, Mark Fowler, Janek Schleicher, chromatic,
227       Peter Scott, Aristotle, Andy Lester, David Wheeler, Jos I. Boumans, Jim
228       Keenan & Perrin for comments, suggestions, bug reports and patches.
229

AUTHOR

231       Adrian Howard <adrianh@quietstars.com>
232
233       If you can spare the time, please drop me a line if you find this mod‐
234       ule useful.
235

LICENCE

250       Copyright 2002-2005 Adrian Howard, All Rights Reserved.
251
252       This program is free software; you can redistribute it and/or modify it
253       under the same terms as Perl itself.
254
255
256
257perl v5.8.8                       2006-09-14                Test::Exception(3)