Test/Warn version 0.02
======================

INSTALLATION

To install this module type the following:

  perl Makefile.PL
  make
  make test
  make install

DEPENDENCIES

This module requires these other modules and libraries:

Test::Builder
Test::Exception
Array::Compare
Sub::Uplevel
List::Util

SYNOPSIS
     use Test::Warn;

     warning_is    {foo(-dri => "/")} "Unknown Parameter 'dri'", "dri != dir gives warning";
     warnings_are  {bar(1,1)} ["Width very small", "Height very small"];

     warning_is    {add(2,2)} undef, "No warning to calc 2+2"; # or
     warnings_are  {add(2,2)} [],    "No warning to calc 2+2"; # what reads better :-)

     warning_like  {foo(-dri => "/"} qr/unknown param/i, "an unknown parameter test";
     warnings_like {bar(1,1)} [qr/width.*small/i, qr/height.*small/i];

     warning_is    {foo()} {carped => 'didn't found the right parameters'};
     warnings_like {foo()} [qr/undefined/,qr/undefined/,{carped => qr/no result/i}];

     [NOT IMPLEMENTED YET]
     warning_like {foo(undef)}                'uninitialized';
     warning_like {bar(file => '/etc/passwd'} 'io';

DESCRIPTION
   This module provides a few convenience methods for testing warning based
   code.

   If you are not already familiar with the Test::More manpage now would be
   the time to go take a look.

 FUNCTIONS
   warning_is BLOCK STRING, TEST_NAME
       Tests that BLOCK gives exactly the one specificated warning. The
       test fails if the BLOCK warns more then one times or doesn't warn.
       If the string is undef, then the tests succeeds iff the BLOCK
       doesn't give any warning. Another way to say that there aren't ary
       warnings in the block, is "warnings_are {foo()} [], "no warnings
       in"".

       If you want to test for a warning given by carp, You have to write
       something like: "warning_is {carp "msg"} {carped =" 'msg'}, "Test
       for a carped warning">. The test will fail, if a "normal" warning is
       found instead of a "carped" one.

       Note: "warn "foo"" would print something like "foo at -e line 1".
       This method ignores everything after the at. That means, to match
       this warning you would have to call "warning_is {warn "foo"} "foo",
       "Foo succeeded"". If you need to test for a warning at an exactly
       line, try better something like "warning_like {warn "foo"} qr/at
       XYZ.dat line 5/".

       warning_is and warning_are are only aliases to the same method. So
       you also could write "warning_is {foo()} [], "no warning"" or
       something similar. I decided me to give two methods to have some
       better readable method names.

       A true value is returned if the test succeeds, false otherwise.

       The test name is optional, but recommended.

   warnings_are BLOCK ARRAYREF, TEST_NAME
       Tests to see that BLOCK gives exactly the specificated warnings. The
       test fails if the BLOCK warns a different number than the size of
       the ARRAYREf would have expected. If the ARRAYREF is equal to [],
       then the test succeeds iff the BLOCK doesn't give any warning.

       Please read also the notes to warning_is as these methods are only
       aliases.

       At the moment, more than one tests for carped warnings look that
       way: "warnings_are {carp "c1"; carp "c2"} [{carped =" 'c1'},{carped
       => 'c2'}];>. I'm working for a better solution.

   warning_like BLOCK REGEXP, TEST_NAME
       Tests that BLOCK gives exactly one warning and it can be matched to
       the given regexp. If the string is undef, then the tests succeeds
       iff the BLOCK doesn't give any warning.

       The REGEXP is matched after the whole warn line, which consists in
       general of "WARNING at __FILE__ line __LINE__". So you can check for
       a warning in at File Foo.pm line 5 with "warning_like {bar()} qr/at
       Foo.pm line 5/, "Testname"". I don't know whether it's sensful to do
       such a test :-( However, you should be prepared as a matching with
       'at', 'file', '\d' or similar will always pass. Think to the
       qr/^foo/ if you want to test for warning "foo something" in file
       foo.pl.

       You can also write the regexp in a string as "/.../" instead of
       using the qr/.../ syntax. Note that the slashes are important in the
       string, as strings without slashes are reserved for future versions
       (to match warning categories as can be seen in the perllexwarn man
       page).

       Similar to "warning_is", you can test for warnings via "carp" with:
       "warning_like {bar()} {carped =" qr/bar called too early/i};>

       Similar to "warning_is"/"warnings_are", "warning_like" and
       "warnings_like" are only aliases to the same methods.

       A true value is returned if the test succeeds, false otherwise.

       The test name is optional, but recommended.

   warnings_like BLOCK ARRAYREF, TEST_NAME
       Tests to see that BLOCK gives exactly the number of the specificated
       warnings and all the warnings have to match in the defined order to
       the passed regexes.

       Please read also the notes to warning_like as these methods are only
       aliases.

       Similar to "warnings_are", you can test for multiple warnings via
       "carp" with: "warnings_like {foo()}
       [qr/undefined/,qr/undefined/,{carped =" qr/no result/i}];>

 EXPORT
   "warning_is", "warnings_are", "warning_like", "warnings_like" by
   default.

BUGS
   This bad documentation, I'll make it better the next time.

   I only tested it with the simple "warn" function. It should work also
   with "Carp::carp" method, but I think, there will be problems using
   <Carp::clucks> or any other warning that gives a devel stack.

   If a method has it's own warn handler, overwriting $SIG{__WARN__}, my
   test warning methods won't get these warnings.

TODO
   Improve this documentation.

   Allow to define to test for more then one carping more convienience,
   like:

     warnings_like {foo()} [qr/division by zero/i,
                            {carped => qr/no result/i,
                                       qr/used default output/i}];

   "warning_like BLOCK CATEGORY, TEST_NAME" where CATEGORY is a warning
   category defined in perllexwarn.

   The code has many parts doubled. This is really awkward and has to be
   changed.

   Please feel free to suggest me any improvements.

SEE ALSO
   Have a look to the similar Test::Exception module.

THANKS
   Many thanks to Adrian Howard, Chromatic and Michael G. Schwern, who has
   given me a lot of ideas.

AUTHOR
   Janek Schleicher, <[email protected]>

COPYRIGHT AND LICENSE
   Copyright 2002 by Janek Schleicher

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.