X-Git-Url: http://git.maemo.org/git/?p=dh-make-perl;a=blobdiff_plain;f=dev%2Fi386%2Flibtest-exception-perl%2Flibtest-exception-perl-0.27%2FREADME;fp=dev%2Fi386%2Flibtest-exception-perl%2Flibtest-exception-perl-0.27%2FREADME;h=abe16147319271012b167f990dcf3ef78c76bfb4;hp=0000000000000000000000000000000000000000;hb=8977e561d8a9eae6959218b0306c9df2056a38a9;hpb=df794b845212301ea0d267c919232538bfef356a diff --git a/dev/i386/libtest-exception-perl/libtest-exception-perl-0.27/README b/dev/i386/libtest-exception-perl/libtest-exception-perl-0.27/README new file mode 100644 index 0000000..abe1614 --- /dev/null +++ b/dev/i386/libtest-exception-perl/libtest-exception-perl-0.27/README @@ -0,0 +1,299 @@ +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 = ; + 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 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 . + +COMMUNITY + perl-qa + If you are interested in testing using Perl I recommend you visit + and join the excellent perl-qa mailing list. + See for details on + how to subscribe. + + perlmonks + You can find users of Test::Exception, including the module author, + on . 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 + . + + AnnoCPAN + AnnoCPAN is a web site that allows community annotations of Perl + module documentation. The Test::Exception annotations can be found + at . + +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 + , with an RSS feed of + changes at . + +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 + + If you can spare the time, please drop me a line if you find this module + useful. + +SEE ALSO + + 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. + + + Overview of some of the many testing modules available on CPAN. + + + 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. +