--- /dev/null
+NAME
+ Test::Exception - Test exception based code
+
+SYNOPSIS
+ use Test::More tests => 5;
+ use Test::Exception;
+
+ # or if you don't need Test::More
+
+ use Test::Exception tests => 5;
+
+ # then...
+
+ # Check that the stringified exception matches given regex
+ throws_ok { $foo->method } qr/division by zero/, 'zero caught okay';
+
+ # Check an exception of the given class (or subclass) is thrown
+ throws_ok { $foo->method } 'Error::Simple', 'simple error thrown';
+
+ # all Test::Exceptions subroutines are guaranteed to preserve the state
+ # of $@ so you can do things like this after throws_ok and dies_ok
+ like $@, 'what the stringified exception should look like';
+
+ # Check that something died - we do not care why
+ dies_ok { $foo->method } 'expecting to die';
+
+ # Check that something did not die
+ lives_ok { $foo->method } 'expecting to live';
+
+ # Check that a test runs without an exception
+ lives_and { is $foo->method, 42 } 'method is 42';
+
+ # or if you don't like prototyped functions
+
+ throws_ok( sub { $foo->method }, qr/division by zero/,
+ 'zero caught okay' );
+ throws_ok( sub { $foo->method }, 'Error::Simple',
+ 'simple error thrown' );
+ dies_ok( sub { $foo->method }, 'expecting to die' );
+ lives_ok( sub { $foo->method }, 'expecting to live' );
+ lives_and( sub { is $foo->method, 42 }, 'method is 42' );
+
+DESCRIPTION
+ This module provides a few convenience methods for testing exception
+ based code. It is built with Test::Builder and plays happily with
+ Test::More and friends.
+
+ If you are not already familiar with Test::More now would be the time to
+ go take a look.
+
+ You can specify the test plan when you "use Test::Exception" in the same
+ way as "use Test::More". See Test::More for details.
+
+ NOTE: Test::Exception only checks for exceptions. It will ignore other
+ methods of stopping program execution - including exit(). If you have an
+ exit() in evalled code Test::Exception will not catch this with any of
+ its testing functions.
+
+ throws_ok
+ Tests to see that a specific exception is thrown. throws_ok() has
+ two forms:
+
+ throws_ok BLOCK REGEX, TEST_DESCRIPTION
+ throws_ok BLOCK CLASS, TEST_DESCRIPTION
+
+ In the first form the test passes if the stringified exception
+ matches the give regular expression. For example:
+
+ throws_ok { read_file( 'unreadable' ) } qr/No file/, 'no file';
+
+ If your perl does not support "qr//" you can also pass a regex-like
+ string, for example:
+
+ throws_ok { read_file( 'unreadable' ) } '/No file/', 'no file';
+
+ The second form of throws_ok() test passes if the exception is of
+ the same class as the one supplied, or a subclass of that class. For
+ example:
+
+ throws_ok { $foo->bar } "Error::Simple", 'simple error';
+
+ Will only pass if the "bar" method throws an Error::Simple
+ exception, or a subclass of an Error::Simple exception.
+
+ You can get the same effect by passing an instance of the exception
+ you want to look for. The following is equivalent to the previous
+ example:
+
+ my $SIMPLE = Error::Simple->new;
+ throws_ok { $foo->bar } $SIMPLE, 'simple error';
+
+ Should a throws_ok() test fail it produces appropriate diagnostic
+ messages. For example:
+
+ not ok 3 - simple error
+ # Failed test (test.t at line 48)
+ # expecting: Error::Simple exception
+ # found: normal exit
+
+ Like all other Test::Exception functions you can avoid prototypes by
+ passing a subroutine explicitly:
+
+ throws_ok( sub {$foo->bar}, "Error::Simple", 'simple error' );
+
+ A true value is returned if the test succeeds, false otherwise. On
+ exit $@ is guaranteed to be the cause of death (if any).
+
+ A description of the exception being checked is used if no optional
+ test description is passed.
+
+ dies_ok
+ Checks that a piece of code dies, rather than returning normally.
+ For example:
+
+ sub div {
+ my ( $a, $b ) = @_;
+ return $a / $b;
+ };
+
+ dies_ok { div( 1, 0 ) } 'divide by zero detected';
+
+ # or if you don't like prototypes
+ dies_ok( sub { div( 1, 0 ) }, 'divide by zero detected' );
+
+ A true value is returned if the test succeeds, false otherwise. On
+ exit $@ is guaranteed to be the cause of death (if any).
+
+ Remember: This test will pass if the code dies for any reason. If
+ you care about the reason it might be more sensible to write a more
+ specific test using throws_ok().
+
+ The test description is optional, but recommended.
+
+ lives_ok
+ Checks that a piece of code doesn't die. This allows your test
+ script to continue, rather than aborting if you get an unexpected
+ exception. For example:
+
+ sub read_file {
+ my $file = shift;
+ local $/;
+ open my $fh, '<', $file or die "open failed ($!)\n";
+ $file = <FILE>;
+ return $file;
+ };
+
+ my $file;
+ lives_ok { $file = read_file('test.txt') } 'file read';
+
+ # or if you don't like prototypes
+ lives_ok( sub { $file = read_file('test.txt') }, 'file read' );
+
+ Should a lives_ok() test fail it produces appropriate diagnostic
+ messages. For example:
+
+ not ok 1 - file read
+ # Failed test (test.t at line 15)
+ # died: open failed (No such file or directory)
+
+ A true value is returned if the test succeeds, false otherwise. On
+ exit $@ is guaranteed to be the cause of death (if any).
+
+ The test description is optional, but recommended.
+
+ lives_and
+ Run a test that may throw an exception. For example, instead of
+ doing:
+
+ my $file;
+ lives_ok { $file = read_file('answer.txt') } 'read_file worked';
+ is $file, "42", 'answer was 42';
+
+ You can use lives_and() like this:
+
+ lives_and { is read_file('answer.txt'), "42" } 'answer is 42';
+ # or if you don't like prototypes
+ lives_and(sub {is read_file('answer.txt'), "42"}, 'answer is 42');
+
+ Which is the same as doing
+
+ is read_file('answer.txt'), "42\n", 'answer is 42';
+
+ unless "read_file('answer.txt')" dies, in which case you get the
+ same kind of error as lives_ok()
+
+ not ok 1 - answer is 42
+ # Failed test (test.t at line 15)
+ # died: open failed (No such file or directory)
+
+ A true value is returned if the test succeeds, false otherwise. On
+ exit $@ is guaranteed to be the cause of death (if any).
+
+ The test description is optional, but recommended.
+
+SKIPPING TEST::EXCEPTION TESTS
+ Sometimes we want to use Test::Exception tests in a test suite, but
+ don't want to force the user to have Test::Exception installed. One way
+ to do this is to skip the tests if Test::Exception is absent. You can do
+ this with code something like this:
+
+ use strict;
+ use warnings;
+ use Test::More;
+
+ BEGIN {
+ eval "use Test::Exception";
+ plan skip_all => "Test::Exception needed" if $@;
+ }
+
+ plan tests => 2;
+ # ... tests that need Test::Exception ...
+
+ Note that we load Test::Exception in a "BEGIN" block ensuring that the
+ subroutine prototypes are in place before the rest of the test script is
+ compiled.
+
+BUGS
+ There are some edge cases in Perl's exception handling where
+ Test::Exception will miss exceptions thrown in DESTROY blocks. See the
+ RT bug <http://rt.cpan.org/Ticket/Display.html?id=24678> for details,
+ along with the t/edge-cases.t in the distribution test suite. These will
+ be addressed in a future Test::Exception release.
+
+ If you find any more bugs please let me know by e-mail, or report the
+ problem with <http://rt.cpan.org/>.
+
+COMMUNITY
+ perl-qa
+ If you are interested in testing using Perl I recommend you visit
+ <http://qa.perl.org/> and join the excellent perl-qa mailing list.
+ See <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on
+ how to subscribe.
+
+ perlmonks
+ You can find users of Test::Exception, including the module author,
+ on <http://www.perlmonks.org/>. Feel free to ask questions on
+ Test::Exception there.
+
+ CPAN::Forum
+ The CPAN Forum is a web forum for discussing Perl's CPAN modules.
+ The Test::Exception forum can be found at
+ <http://www.cpanforum.com/dist/Test-Exception>.
+
+ AnnoCPAN
+ AnnoCPAN is a web site that allows community annotations of Perl
+ module documentation. The Test::Exception annotations can be found
+ at <http://annocpan.org/~ADIE/Test-Exception/>.
+
+TO DO
+ If you think this module should do something that it doesn't (or does
+ something that it shouldn't) please let me know.
+
+ You can see my current to do list at
+ <http://adrianh.tadalist.com/lists/public/15421>, with an RSS feed of
+ changes at <http://adrianh.tadalist.com/lists/feed_public/15421>.
+
+ACKNOWLEDGMENTS
+ Thanks to chromatic and Michael G Schwern for the excellent
+ Test::Builder, without which this module wouldn't be possible.
+
+ Thanks to Adam Kennedy, Andy Lester, Aristotle Pagaltzis, Ben Prew, Cees
+ Hek, Chris Dolan, chromatic, Curt Sampson, David Cantrell, David Golden,
+ David Wheeler, Janek Schleicher, Jim Keenan, Jos I. Boumans, Joshua ben
+ Jore, Jost Krieger, Mark Fowler, Michael G Schwern, Nadim Khemir, Paul
+ McCann, Perrin Harkins, Peter Scott, Rob Muhlestein Scott R. Godin,
+ Steve Purkis, Steve, Tim Bunce, and various anonymous folk for comments,
+ suggestions, bug reports and patches.
+
+AUTHOR
+ Adrian Howard <adrianh@quietstars.com>
+
+ If you can spare the time, please drop me a line if you find this module
+ useful.
+
+SEE ALSO
+ <http://del.icio.us/tag/Test::Exception>
+ Delicious links on Test::Exception.
+
+ Test::Warn & Test::NoWarnings
+ Modules to help test warnings.
+
+ Test::Builder
+ Support module for building test libraries.
+
+ Test::Simple & Test::More
+ Basic utilities for writing tests.
+
+ <http://qa.perl.org/test-modules.html>
+ Overview of some of the many testing modules available on CPAN.
+
+ <http://del.icio.us/tag/perl+testing>
+ Delicious links on perl testing.
+
+LICENCE
+ Copyright 2002-2007 Adrian Howard, All Rights Reserved.
+
+ This program is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself.
+
projects / dh-make-perl / blobdiff