1Warn(3) User Contributed Perl Documentation Warn(3)
2
6 Test::Warn - Perl extension to test methods for warnings
7
9 use Test::Warn;
10 warning_is {foo(-dri => "/")} "Unknown Parameter 'dri'", "dri != dir gives warning";
12 warnings_are {bar(1,1)} ["Width very small", "Height very small"];
13 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 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 warning_is {foo()} {carped => "didn't found the right parameters"};
21 warnings_like {foo()} [qr/undefined/,qr/undefined/,{carped => qr/no result/i}];
22 warning_like {foo(undef)} 'uninitialized';
24 warning_like {bar(file => '/etc/passwd')} 'io';
25 warning_like {eval q/"$x"; $x;/}
27 [qw/void uninitialized/],
28 "some warnings at compile time";
29 warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
31
33 A good style of Perl programming calls for a lot of diverse regression
34 tests.
35 This module provides a few convenience methods for testing warning
37 based code.
38 If you are not already familiar with the Test::More manpage now would
40 be the time to go take a look.
41 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 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 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 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 A true value is returned if the test succeeds, false otherwise.
69 The test name is optional, but recommended.
71 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 Please read also the notes to warning_is as these methods are only
79 aliases.
80 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 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 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 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 Similar to "warning_is", you can test for warnings via "carp" with:
108 "warning_like {bar()} {carped =" qr/bar called too early/i};>
109 Similar to "warning_is"/"warnings_are", "warning_like" and
111 "warnings_like" are only aliases to the same methods.
112 A true value is returned if the test succeeds, false otherwise.
114 The test name is optional, but recommended.
116 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 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 Note, that warnings occuring at compile time, can only be catched
131 in an eval block. So
132 warning_like {eval q/"$x"; $x;/}
134 [qw/void uninitialized/],
135 "some warnings at compile time";
136 will work, while it wouldn't work without the eval.
138 Note, that it isn't possible yet, to test for own categories,
140 created with warnings::register.
141 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 Please read also the notes to warning_like as these methods are
148 only aliases.
149 Similar to "warnings_are", you can test for multiple warnings via
151 "carp" and for warning categories, too:
152 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 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 warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
169 warnings_exist {...} ['uninitialized'], "Expected warning is thrown";
171 EXPORT
173 "warning_is", "warnings_are", "warning_like", "warnings_like",
174 "warnings_exist" by default.
175
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 If a method has it's own warn handler, overwriting $SIG{__WARN__}, my
184 test warning methods won't get these warnings.
185 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
191 Improve this documentation.
192 The code has some parts doubled - especially in the test scripts. This
194 is really awkward and has to be changed.
195 Please feel free to suggest me any improvements.
197
199 Have a look to the similar Test::Exception module. Test::Trap
200
202 Many thanks to Adrian Howard, chromatic and Michael G. Schwern, who
203 have given me a lot of ideas.
204
206 Janek Schleicher, <bigj AT kamelfreund.de>
207
209 Copyright 2002 by Janek Schleicher
210 Copyright 2007-2009 by Alexandr Ciornii, <http://chorny.net/>
212 This library is free software; you can redistribute it and/or modify it
214 under the same terms as Perl itself.
215perl v5.12.0 2009-08-29 Warn(3)