1NAME 2 Test::Exception - Test exception based code 3 4SYNOPSIS 5 use Test::More tests => 5; 6 use Test::Exception; 7 8 # or if you don't need Test::More 9 10 use Test::Exception tests => 5; 11 12 # then... 13 14 # Check that the stringified exception matches given regex 15 throws_ok { $foo->method } qr/division by zero/, 'zero caught okay'; 16 17 # Check an exception of the given class (or subclass) is thrown 18 throws_ok { $foo->method } 'Error::Simple', 'simple error thrown'; 19 20 # all Test::Exceptions subroutines are guaranteed to preserve the state 21 # of $@ so you can do things like this after throws_ok and dies_ok 22 like $@, 'what the stringified exception should look like'; 23 24 # Check that something died - we do not care why 25 dies_ok { $foo->method } 'expecting to die'; 26 27 # Check that something did not die 28 lives_ok { $foo->method } 'expecting to live'; 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 throws_ok( sub { $foo->method }, qr/division by zero/, 36 'zero caught okay' ); 37 throws_ok( sub { $foo->method }, 'Error::Simple', 38 'simple error thrown' ); 39 dies_ok( sub { $foo->method }, 'expecting to die' ); 40 lives_ok( sub { $foo->method }, 'expecting to live' ); 41 lives_and( sub { is $foo->method, 42 }, 'method is 42' ); 42 43DESCRIPTION 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 to 49 go take a look. 50 51 You can specify the test plan when you "use Test::Exception" in the same 52 way as "use Test::More". See Test::More for details. 53 54 NOTE: Test::Exception only checks for exceptions. It will ignore other 55 methods of stopping program execution - including exit(). If you have an 56 exit() in evalled code Test::Exception will not catch this with any of 57 its testing functions. 58 59 throws_ok 60 Tests to see that a specific exception is thrown. throws_ok() has 61 two forms: 62 63 throws_ok BLOCK REGEX, TEST_DESCRIPTION 64 throws_ok BLOCK CLASS, TEST_DESCRIPTION 65 66 In the first form the test passes if the stringified exception 67 matches the give regular expression. For example: 68 69 throws_ok { read_file( 'unreadable' ) } qr/No file/, 'no file'; 70 71 If your perl does not support "qr//" you can also pass a regex-like 72 string, for example: 73 74 throws_ok { read_file( 'unreadable' ) } '/No file/', 'no file'; 75 76 The second form of throws_ok() test passes if the exception is of 77 the same class as the one supplied, or a subclass of that class. For 78 example: 79 80 throws_ok { $foo->bar } "Error::Simple", 'simple error'; 81 82 Will only pass if the "bar" method throws an Error::Simple 83 exception, or a subclass of an Error::Simple exception. 84 85 You can get the same effect by passing an instance of the exception 86 you want to look for. The following is equivalent to the previous 87 example: 88 89 my $SIMPLE = Error::Simple->new; 90 throws_ok { $foo->bar } $SIMPLE, 'simple error'; 91 92 Should a throws_ok() test fail it produces appropriate diagnostic 93 messages. For example: 94 95 not ok 3 - simple error 96 # Failed test (test.t at line 48) 97 # expecting: Error::Simple exception 98 # found: normal exit 99 100 Like all other Test::Exception functions you can avoid prototypes by 101 passing a subroutine explicitly: 102 103 throws_ok( sub {$foo->bar}, "Error::Simple", 'simple error' ); 104 105 A true value is returned if the test succeeds, false otherwise. On 106 exit $@ is guaranteed to be the cause of death (if any). 107 108 A description of the exception being checked is used if no optional 109 test description is passed. 110 111 dies_ok 112 Checks that a piece of code dies, rather than returning normally. 113 For example: 114 115 sub div { 116 my ( $a, $b ) = @_; 117 return $a / $b; 118 }; 119 120 dies_ok { div( 1, 0 ) } 'divide by zero detected'; 121 122 # or if you don't like prototypes 123 dies_ok( sub { div( 1, 0 ) }, 'divide by zero detected' ); 124 125 A true value is returned if the test succeeds, false otherwise. On 126 exit $@ is guaranteed to be the cause of death (if any). 127 128 Remember: This test will pass if the code dies for any reason. If 129 you care about the reason it might be more sensible to write a more 130 specific test using throws_ok(). 131 132 The test description is optional, but recommended. 133 134 lives_ok 135 Checks that a piece of code doesn't die. This allows your test 136 script to continue, rather than aborting if you get an unexpected 137 exception. For example: 138 139 sub read_file { 140 my $file = shift; 141 local $/; 142 open my $fh, '<', $file or die "open failed ($!)\n"; 143 $file = <FILE>; 144 return $file; 145 }; 146 147 my $file; 148 lives_ok { $file = read_file('test.txt') } 'file read'; 149 150 # or if you don't like prototypes 151 lives_ok( sub { $file = read_file('test.txt') }, 'file read' ); 152 153 Should a lives_ok() test fail it produces appropriate diagnostic 154 messages. For example: 155 156 not ok 1 - file read 157 # Failed test (test.t at line 15) 158 # died: open failed (No such file or directory) 159 160 A true value is returned if the test succeeds, false otherwise. On 161 exit $@ is guaranteed to be the cause of death (if any). 162 163 The test description is optional, but recommended. 164 165 lives_and 166 Run a test that may throw an exception. For example, instead of 167 doing: 168 169 my $file; 170 lives_ok { $file = read_file('answer.txt') } 'read_file worked'; 171 is $file, "42", 'answer was 42'; 172 173 You can use lives_and() like this: 174 175 lives_and { is read_file('answer.txt'), "42" } 'answer is 42'; 176 # or if you don't like prototypes 177 lives_and(sub {is read_file('answer.txt'), "42"}, 'answer is 42'); 178 179 Which is the same as doing 180 181 is read_file('answer.txt'), "42\n", 'answer is 42'; 182 183 unless "read_file('answer.txt')" dies, in which case you get the 184 same kind of error as lives_ok() 185 186 not ok 1 - answer is 42 187 # Failed test (test.t at line 15) 188 # died: open failed (No such file or directory) 189 190 A true value is returned if the test succeeds, false otherwise. On 191 exit $@ is guaranteed to be the cause of death (if any). 192 193 The test description is optional, but recommended. 194 195SKIPPING TEST::EXCEPTION TESTS 196 Sometimes we want to use Test::Exception tests in a test suite, but 197 don't want to force the user to have Test::Exception installed. One way 198 to do this is to skip the tests if Test::Exception is absent. You can do 199 this with code something like this: 200 201 use strict; 202 use warnings; 203 use Test::More; 204 205 BEGIN { 206 eval "use Test::Exception"; 207 plan skip_all => "Test::Exception needed" if $@; 208 } 209 210 plan tests => 2; 211 # ... tests that need Test::Exception ... 212 213 Note that we load Test::Exception in a "BEGIN" block ensuring that the 214 subroutine prototypes are in place before the rest of the test script is 215 compiled. 216 217BUGS 218 There are some edge cases in Perl's exception handling where 219 Test::Exception will miss exceptions thrown in DESTROY blocks. See the 220 RT bug <http://rt.cpan.org/Ticket/Display.html?id=24678> for details, 221 along with the t/edge-cases.t in the distribution test suite. These will 222 be addressed in a future Test::Exception release. 223 224 If you find any more bugs please let me know by e-mail, or report the 225 problem with <http://rt.cpan.org/>. 226 227COMMUNITY 228 perl-qa 229 If you are interested in testing using Perl I recommend you visit 230 <http://qa.perl.org/> and join the excellent perl-qa mailing list. 231 See <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on 232 how to subscribe. 233 234 perlmonks 235 You can find users of Test::Exception, including the module author, 236 on <http://www.perlmonks.org/>. Feel free to ask questions on 237 Test::Exception there. 238 239 CPAN::Forum 240 The CPAN Forum is a web forum for discussing Perl's CPAN modules. 241 The Test::Exception forum can be found at 242 <http://www.cpanforum.com/dist/Test-Exception>. 243 244 AnnoCPAN 245 AnnoCPAN is a web site that allows community annotations of Perl 246 module documentation. The Test::Exception annotations can be found 247 at <http://annocpan.org/~ADIE/Test-Exception/>. 248 249TO DO 250 If you think this module should do something that it doesn't (or does 251 something that it shouldn't) please let me know. 252 253 You can see my current to do list at 254 <http://adrianh.tadalist.com/lists/public/15421>, with an RSS feed of 255 changes at <http://adrianh.tadalist.com/lists/feed_public/15421>. 256 257ACKNOWLEDGMENTS 258 Thanks to chromatic and Michael G Schwern for the excellent 259 Test::Builder, without which this module wouldn't be possible. 260 261 Thanks to Adam Kennedy, Andy Lester, Aristotle Pagaltzis, Ben Prew, Cees 262 Hek, Chris Dolan, chromatic, Curt Sampson, David Cantrell, David Golden, 263 David Wheeler, Janek Schleicher, Jim Keenan, Jos I. Boumans, Joshua ben 264 Jore, Jost Krieger, Mark Fowler, Michael G Schwern, Nadim Khemir, Paul 265 McCann, Perrin Harkins, Peter Scott, Ricardo Signes, Rob Muhlestein 266 Scott R. Godin, Steve Purkis, Steve, Tim Bunce, and various anonymous 267 folk for comments, suggestions, bug reports and patches. 268 269AUTHOR 270 Adrian Howard <adrianh@quietstars.com> 271 272 If you can spare the time, please drop me a line if you find this module 273 useful. 274 275SEE ALSO 276 <http://del.icio.us/tag/Test::Exception> 277 Delicious links on Test::Exception. 278 279 Test::Warn & Test::NoWarnings 280 Modules to help test warnings. 281 282 Test::Builder 283 Support module for building test libraries. 284 285 Test::Simple & Test::More 286 Basic utilities for writing tests. 287 288 <http://qa.perl.org/test-modules.html> 289 Overview of some of the many testing modules available on CPAN. 290 291 <http://del.icio.us/tag/perl+testing> 292 Delicious links on perl testing. 293 294LICENCE 295 Copyright 2002-2007 Adrian Howard, All Rights Reserved. 296 297 This program is free software; you can redistribute it and/or modify it 298 under the same terms as Perl itself. 299 300