1Warn(3)               User Contributed Perl Documentation              Warn(3)
2
3
4

NAME

6       Test::Warn - Perl extension to test methods for warnings
7

SYNOPSIS

9         use Test::Warn;
10
11         warning_is    {foo(-dri => "/")} "Unknown Parameter 'dri'", "dri != dir gives warning";
12         warnings_are  {bar(1,1)} ["Width very small", "Height very small"];
13
14         warning_is    {add(2,2)} undef, "No warning to calc 2+2"; # or
15         warnings_are  {add(2,2)} [],    "No warning to calc 2+2"; # what reads better :-)
16
17         warning_like  {foo(-dri => "/")} qr/unknown param/i, "an unknown parameter test";
18         warnings_like {bar(1,1)} [qr/width.*small/i, qr/height.*small/i];
19
20         warning_is    {foo()} {carped => "didn't found the right parameters"};
21         warnings_like {foo()} [qr/undefined/,qr/undefined/,{carped => qr/no result/i}];
22
23         warning_like {foo(undef)}                 'uninitialized';
24         warning_like {bar(file => '/etc/passwd')} 'io';
25
26         warning_like {eval q/"$x"; $x;/}
27                      [qw/void uninitialized/],
28                      "some warnings at compile time";
29
30         warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
31

DESCRIPTION

33       A good style of Perl programming calls for a lot of diverse regression
34       tests.
35
36       This module provides a few convenience methods for testing warning
37       based code.
38
39       If you are not already familiar with the Test::More manpage now would
40       be the time to go take a look.
41
42   FUNCTIONS
43       warning_is BLOCK STRING, TEST_NAME
44           Tests that BLOCK gives exactly the one specificated warning.  The
45           test fails if the BLOCK warns more then one times or doesn't warn.
46           If the string is undef, then the tests succeeds if the BLOCK
47           doesn't give any warning.  Another way to say that there aren't any
48           warnings in the block, is "warnings_are {foo()} [], "no warnings
49           in"".
50
51           If you want to test for a warning given by carp, You have to write
52           something like: "warning_is {carp "msg"} {carped => 'msg'}, "Test
53           for a carped warning"".  The test will fail, if a "normal" warning
54           is found instead of a "carped" one.
55
56           Note: "warn "foo"" would print something like "foo at -e line 1".
57           This method ignores everything after the at. That means, to match
58           this warning you would have to call "warning_is {warn "foo"} "foo",
59           "Foo succeeded"".  If you need to test for a warning at an exactly
60           line, try better something like "warning_like {warn "foo"} qr/at
61           XYZ.dat line 5/".
62
63           warning_is and warning_are are only aliases to the same method.  So
64           you also could write "warning_is {foo()} [], "no warning"" or
65           something similar.  I decided to give two methods to have some
66           better readable method names.
67
68           A true value is returned if the test succeeds, false otherwise.
69
70           The test name is optional, but recommended.
71
72       warnings_are BLOCK ARRAYREF, TEST_NAME
73           Tests to see that BLOCK gives exactly the specificated warnings.
74           The test fails if the BLOCK warns a different number than the size
75           of the ARRAYREf would have expected.  If the ARRAYREF is equal to
76           [], then the test succeeds if the BLOCK doesn't give any warning.
77
78           Please read also the notes to warning_is as these methods are only
79           aliases.
80
81           If you want more than one tests for carped warnings look that way:
82           "warnings_are {carp "c1"; carp "c2"} {carped =" ['c1','c2'];> or
83           "warnings_are {foo()} ["Warning 1", {carped =" ["Carp 1", "Carp
84           2"]}, "Warning 2"]>.  Note that "{carped =" ...}> has always to be
85           a hash ref.
86
87       warning_like BLOCK REGEXP, TEST_NAME
88           Tests that BLOCK gives exactly one warning and it can be matched to
89           the given regexp.  If the string is undef, then the tests succeeds
90           iff the BLOCK doesn't give any warning.
91
92           The REGEXP is matched after the whole warn line, which consists in
93           general of "WARNING at __FILE__ line __LINE__".  So you can check
94           for a warning in at File Foo.pm line 5 with "warning_like {bar()}
95           qr/at Foo.pm line 5/, "Testname"".  I don't know whether it's
96           sensful to do such a test :-( However, you should be prepared as a
97           matching with 'at', 'file', '\d' or similar will always pass.
98           Think to the qr/^foo/ if you want to test for warning "foo
99           something" in file foo.pl.
100
101           You can also write the regexp in a string as "/.../" instead of
102           using the qr/.../ syntax.  Note that the slashes are important in
103           the string, as strings without slashes are reserved for warning
104           categories (to match warning categories as can be seen in the
105           perllexwarn man page).
106
107           Similar to "warning_is", you can test for warnings via "carp" with:
108           "warning_like {bar()} {carped =" qr/bar called too early/i};>
109
110           Similar to "warning_is"/"warnings_are", "warning_like" and
111           "warnings_like" are only aliases to the same methods.
112
113           A true value is returned if the test succeeds, false otherwise.
114
115           The test name is optional, but recommended.
116
117       warning_like BLOCK STRING, TEST_NAME
118           Tests whether a BLOCK gives exactly one warning of the passed
119           category.  The categories are grouped in a tree, like it is
120           expressed in perllexwarn.  Note, that they have the hierarchical
121           structure from perl 5.8.0, wich has a little bit changed to 5.6.1
122           or earlier versions (You can access the internal used tree with
123           $Test::Warn::Categorization::tree, although I wouldn't recommend
124           it)
125
126           Thanks to the grouping in a tree, it's simple possible to test for
127           an 'io' warning, instead for testing for a
128           'closed|exec|layer|newline|pipe|unopened' warning.
129
130           Note, that warnings occuring at compile time, can only be catched
131           in an eval block. So
132
133             warning_like {eval q/"$x"; $x;/}
134                          [qw/void uninitialized/],
135                          "some warnings at compile time";
136
137           will work, while it wouldn't work without the eval.
138
139           Note, that it isn't possible yet, to test for own categories,
140           created with warnings::register.
141
142       warnings_like BLOCK ARRAYREF, TEST_NAME
143           Tests to see that BLOCK gives exactly the number of the
144           specificated warnings and all the warnings have to match in the
145           defined order to the passed regexes.
146
147           Please read also the notes to warning_like as these methods are
148           only aliases.
149
150           Similar to "warnings_are", you can test for multiple warnings via
151           "carp" and for warning categories, too:
152
153             warnings_like {foo()}
154                           [qr/bar warning/,
155                            qr/bar warning/,
156                            {carped => qr/bar warning/i},
157                            'io'
158                           ],
159                           "I hope, you'll never have to write a test for so many warnings :-)";
160
161       warnings_exist BLOCK STRING|ARRAYREF, TEST_NAME
162           Same as warning_like, but will warn() all warnings that do not
163           match the supplied regex/category, instead of registering an error.
164           Use this test when you just want to make sure that specific
165           warnings were generated, and couldn't care less if other warnings
166           happened in the same block of code.
167
168             warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
169
170             warnings_exist {...} ['uninitialized'], "Expected warning is thrown";
171
172   EXPORT
173       "warning_is", "warnings_are", "warning_like", "warnings_like",
174       "warnings_exist" by default.
175

BUGS

177       Please note that warnings with newlines inside are making a lot of
178       trouble.  The only sensible way to handle them is to use are the
179       "warning_like" or "warnings_like" methods. Background for these
180       problems is that there is no really secure way to distinguish between
181       warnings with newlines and a tracing stacktrace.
182
183       If a method has it's own warn handler, overwriting $SIG{__WARN__}, my
184       test warning methods won't get these warnings.
185
186       The "warning_like BLOCK CATEGORY, TEST_NAME" method isn't extremely
187       tested.  Please use this calling style with higher attention and tell
188       me if you find a bug.
189

TODO

191       Improve this documentation.
192
193       The code has some parts doubled - especially in the test scripts.  This
194       is really awkward and has to be changed.
195
196       Please feel free to suggest me any improvements.
197

SEE ALSO

199       Have a look to the similar Test::Exception module. Test::Trap
200

THANKS

202       Many thanks to Adrian Howard, chromatic and Michael G. Schwern, who
203       have given me a lot of ideas.
204

AUTHOR

206       Janek Schleicher, <bigj AT kamelfreund.de>
207
209       Copyright 2002 by Janek Schleicher
210
211       Copyright 2007-2009 by Alexandr Ciornii, <http://chorny.net/>
212
213       This library is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215
216
217
218perl v5.12.0                      2009-08-29                           Warn(3)
Impressum