git.maemo.org Git - pkg-perl/blob - deb-src/libtest-exception-perl/libtest-exception-perl-0.27/README

   1 NAME
   2     Test::Exception - Test exception based code
   3
   4 SYNOPSIS
   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
  43 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 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
 195 SKIPPING 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
 217 BUGS
 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
 227 COMMUNITY
 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
 249 TO 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
 257 ACKNOWLEDGMENTS
 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, Rob Muhlestein Scott R. Godin,
 266     Steve Purkis, Steve, Tim Bunce, and various anonymous folk for comments,
 267     suggestions, bug reports and patches.
 268
 269 AUTHOR
 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
 275 SEE 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
 294 LICENCE
 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