local-lib5/man/man3/Test::Warn.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Warn 3"
 127 .TH Warn 3 "2009-08-29" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Test::Warn \- Perl extension to test methods for warnings
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use Test::Warn;
 138 \&
 139 \&  warning_is    {foo(\-dri => "/")} "Unknown Parameter \*(Aqdri\*(Aq", "dri != dir gives warning";
 140 \&  warnings_are  {bar(1,1)} ["Width very small", "Height very small"];
 141 \&
 142 \&  warning_is    {add(2,2)} undef, "No warning to calc 2+2"; # or
 143 \&  warnings_are  {add(2,2)} [],    "No warning to calc 2+2"; # what reads better :\-)
 144 \&
 145 \&  warning_like  {foo(\-dri => "/")} qr/unknown param/i, "an unknown parameter test";
 146 \&  warnings_like {bar(1,1)} [qr/width.*small/i, qr/height.*small/i];
 147 \&
 148 \&  warning_is    {foo()} {carped => "didn\*(Aqt found the right parameters"};
 149 \&  warnings_like {foo()} [qr/undefined/,qr/undefined/,{carped => qr/no result/i}];
 150 \&
 151 \&  warning_like {foo(undef)}                 \*(Aquninitialized\*(Aq;
 152 \&  warning_like {bar(file => \*(Aq/etc/passwd\*(Aq)} \*(Aqio\*(Aq;
 153 \&
 154 \&  warning_like {eval q/"$x"; $x;/}
 155 \&               [qw/void uninitialized/],
 156 \&               "some warnings at compile time";
 157 \&
 158 \&  warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 A good style of Perl programming calls for a lot of diverse regression tests.
 163 .PP
 164 This module provides a few convenience methods for testing warning based code.
 165 .PP
 166 If you are not already familiar with the Test::More manpage
 167 now would be the time to go take a look.
 168 .SS "\s-1FUNCTIONS\s0"
 169 .IX Subsection "FUNCTIONS"
 170 .IP "warning_is \s-1BLOCK\s0 \s-1STRING\s0, \s-1TEST_NAME\s0" 4
 171 .IX Item "warning_is BLOCK STRING, TEST_NAME"
 172 Tests that \s-1BLOCK\s0 gives exactly the one specificated warning.
 173 The test fails if the \s-1BLOCK\s0 warns more then one times or doesn't warn.
 174 If the string is undef,
 175 then the tests succeeds if the \s-1BLOCK\s0 doesn't give any warning.
 176 Another way to say that there aren't any warnings in the block,
 177 is \f(CW\*(C`warnings_are {foo()} [], "no warnings in"\*(C'\fR.
 178 .Sp
 179 If you want to test for a warning given by carp,
 180 You have to write something like:
 181 \&\f(CW\*(C`warning_is {carp "msg"} {carped => \*(Aqmsg\*(Aq}, "Test for a carped warning"\*(C'\fR.
 182 The test will fail,
 183 if a \*(L"normal\*(R" warning is found instead of a \*(L"carped\*(R" one.
 184 .Sp
 185 Note: \f(CW\*(C`warn "foo"\*(C'\fR would print something like \f(CW\*(C`foo at \-e line 1\*(C'\fR.
 186 This method ignores everything after the at. That means, to match this warning
 187 you would have to call \f(CW\*(C`warning_is {warn "foo"} "foo", "Foo succeeded"\*(C'\fR.
 188 If you need to test for a warning at an exactly line,
 189 try better something like \f(CW\*(C`warning_like {warn "foo"} qr/at XYZ.dat line 5/\*(C'\fR.
 190 .Sp
 191 warning_is and warning_are are only aliases to the same method.
 192 So you also could write
 193 \&\f(CW\*(C`warning_is {foo()} [], "no warning"\*(C'\fR or something similar.
 194 I decided to give two methods to have some better readable method names.
 195 .Sp
 196 A true value is returned if the test succeeds, false otherwise.
 197 .Sp
 198 The test name is optional, but recommended.
 199 .IP "warnings_are \s-1BLOCK\s0 \s-1ARRAYREF\s0, \s-1TEST_NAME\s0" 4
 200 .IX Item "warnings_are BLOCK ARRAYREF, TEST_NAME"
 201 Tests to see that \s-1BLOCK\s0 gives exactly the specificated warnings.
 202 The test fails if the \s-1BLOCK\s0 warns a different number than the size of the ARRAYREf
 203 would have expected.
 204 If the \s-1ARRAYREF\s0 is equal to [],
 205 then the test succeeds if the \s-1BLOCK\s0 doesn't give any warning.
 206 .Sp
 207 Please read also the notes to warning_is as these methods are only aliases.
 208 .Sp
 209 If you want more than one tests for carped warnings look that way:
 210 \&\f(CW\*(C`warnings_are {carp "c1"; carp "c2"} {carped =\*(C'\fR ['c1','c2'];> or
 211 \&\f(CW\*(C`warnings_are {foo()} ["Warning 1", {carped =\*(C'\fR [\*(L"Carp 1\*(R", \*(L"Carp 2\*(R"]}, \*(L"Warning 2\*(R"]>.
 212 Note that \f(CW\*(C`{carped =\*(C'\fR ...}> has always to be a hash ref.
 213 .IP "warning_like \s-1BLOCK\s0 \s-1REGEXP\s0, \s-1TEST_NAME\s0" 4
 214 .IX Item "warning_like BLOCK REGEXP, TEST_NAME"
 215 Tests that \s-1BLOCK\s0 gives exactly one warning and it can be matched to the given regexp.
 216 If the string is undef,
 217 then the tests succeeds iff the \s-1BLOCK\s0 doesn't give any warning.
 218 .Sp
 219 The \s-1REGEXP\s0 is matched after the whole warn line,
 220 which consists in general of \*(L"\s-1WARNING\s0 at _\|_FILE_\|_ line _\|_LINE_\|_\*(R".
 221 So you can check for a warning in at File Foo.pm line 5 with
 222 \&\f(CW\*(C`warning_like {bar()} qr/at Foo.pm line 5/, "Testname"\*(C'\fR.
 223 I don't know whether it's sensful to do such a test :\-(
 224 However, you should be prepared as a matching with 'at', 'file', '\ed'
 225 or similar will always pass.
 226 Think to the qr/^foo/ if you want to test for warning \*(L"foo something\*(R" in file foo.pl.
 227 .Sp
 228 You can also write the regexp in a string as \*(L"/.../\*(R"
 229 instead of using the qr/.../ syntax.
 230 Note that the slashes are important in the string,
 231 as strings without slashes are reserved for warning categories
 232 (to match warning categories as can be seen in the perllexwarn man page).
 233 .Sp
 234 Similar to \f(CW\*(C`warning_is\*(C'\fR,
 235 you can test for warnings via \f(CW\*(C`carp\*(C'\fR with:
 236 \&\f(CW\*(C`warning_like {bar()} {carped =\*(C'\fR qr/bar called too early/i};>
 237 .Sp
 238 Similar to \f(CW\*(C`warning_is\*(C'\fR/\f(CW\*(C`warnings_are\*(C'\fR,
 239 \&\f(CW\*(C`warning_like\*(C'\fR and \f(CW\*(C`warnings_like\*(C'\fR are only aliases to the same methods.
 240 .Sp
 241 A true value is returned if the test succeeds, false otherwise.
 242 .Sp
 243 The test name is optional, but recommended.
 244 .IP "warning_like \s-1BLOCK\s0 \s-1STRING\s0, \s-1TEST_NAME\s0" 4
 245 .IX Item "warning_like BLOCK STRING, TEST_NAME"
 246 Tests whether a \s-1BLOCK\s0 gives exactly one warning of the passed category.
 247 The categories are grouped in a tree,
 248 like it is expressed in perllexwarn.
 249 Note, that they have the hierarchical structure from perl 5.8.0,
 250 wich has a little bit changed to 5.6.1 or earlier versions
 251 (You can access the internal used tree with \f(CW$Test::Warn::Categorization::tree\fR,
 252 although I wouldn't recommend it)
 253 .Sp
 254 Thanks to the grouping in a tree,
 255 it's simple possible to test for an 'io' warning,
 256 instead for testing for a 'closed|exec|layer|newline|pipe|unopened' warning.
 257 .Sp
 258 Note, that warnings occuring at compile time,
 259 can only be catched in an eval block. So
 260 .Sp
 261 .Vb 3
 262 \&  warning_like {eval q/"$x"; $x;/}
 263 \&               [qw/void uninitialized/],
 264 \&               "some warnings at compile time";
 265 .Ve
 266 .Sp
 267 will work,
 268 while it wouldn't work without the eval.
 269 .Sp
 270 Note, that it isn't possible yet,
 271 to test for own categories,
 272 created with warnings::register.
 273 .IP "warnings_like \s-1BLOCK\s0 \s-1ARRAYREF\s0, \s-1TEST_NAME\s0" 4
 274 .IX Item "warnings_like BLOCK ARRAYREF, TEST_NAME"
 275 Tests to see that \s-1BLOCK\s0 gives exactly the number of the specificated warnings
 276 and all the warnings have to match in the defined order to the
 277 passed regexes.
 278 .Sp
 279 Please read also the notes to warning_like as these methods are only aliases.
 280 .Sp
 281 Similar to \f(CW\*(C`warnings_are\*(C'\fR,
 282 you can test for multiple warnings via \f(CW\*(C`carp\*(C'\fR
 283 and for warning categories, too:
 284 .Sp
 285 .Vb 7
 286 \&  warnings_like {foo()}
 287 \&                [qr/bar warning/,
 288 \&                 qr/bar warning/,
 289 \&                 {carped => qr/bar warning/i},
 290 \&                 \*(Aqio\*(Aq
 291 \&                ],
 292 \&                "I hope, you\*(Aqll never have to write a test for so many warnings :\-)";
 293 .Ve
 294 .IP "warnings_exist \s-1BLOCK\s0 STRING|ARRAYREF, \s-1TEST_NAME\s0" 4
 295 .IX Item "warnings_exist BLOCK STRING|ARRAYREF, TEST_NAME"
 296 Same as warning_like, but will \fIwarn()\fR all warnings that do not match the supplied regex/category,
 297 instead of registering an error. Use this test when you just want to make sure that specific
 298 warnings were generated, and couldn't care less if other warnings happened in the same block
 299 of code.
 300 .Sp
 301 .Vb 1
 302 \&  warnings_exist {...} [qr/expected warning/], "Expected warning is thrown";
 303 \&
 304 \&  warnings_exist {...} [\*(Aquninitialized\*(Aq], "Expected warning is thrown";
 305 .Ve
 306 .SS "\s-1EXPORT\s0"
 307 .IX Subsection "EXPORT"
 308 \&\f(CW\*(C`warning_is\*(C'\fR,
 309 \&\f(CW\*(C`warnings_are\*(C'\fR,
 310 \&\f(CW\*(C`warning_like\*(C'\fR,
 311 \&\f(CW\*(C`warnings_like\*(C'\fR,
 312 \&\f(CW\*(C`warnings_exist\*(C'\fR by default.
 313 .SH "BUGS"
 314 .IX Header "BUGS"
 315 Please note that warnings with newlines inside are making a lot of trouble.
 316 The only sensible way to handle them is to use are the \f(CW\*(C`warning_like\*(C'\fR or
 317 \&\f(CW\*(C`warnings_like\*(C'\fR methods. Background for these problems is that there is no
 318 really secure way to distinguish between warnings with newlines and a tracing
 319 stacktrace.
 320 .PP
 321 If a method has it's own warn handler,
 322 overwriting \f(CW$SIG{_\|_WARN_\|_}\fR,
 323 my test warning methods won't get these warnings.
 324 .PP
 325 The \f(CW\*(C`warning_like BLOCK CATEGORY, TEST_NAME\*(C'\fR method isn't extremely tested.
 326 Please use this calling style with higher attention and
 327 tell me if you find a bug.
 328 .SH "TODO"
 329 .IX Header "TODO"
 330 Improve this documentation.
 331 .PP
 332 The code has some parts doubled \- especially in the test scripts.
 333 This is really awkward and has to be changed.
 334 .PP
 335 Please feel free to suggest me any improvements.
 336 .SH "SEE ALSO"
 337 .IX Header "SEE ALSO"
 338 Have a look to the similar Test::Exception module. Test::Trap
 339 .SH "THANKS"
 340 .IX Header "THANKS"
 341 Many thanks to Adrian Howard, chromatic and Michael G. Schwern,
 342 who have given me a lot of ideas.
 343 .SH "AUTHOR"
 344 .IX Header "AUTHOR"
 345 Janek Schleicher, <bigj \s-1AT\s0 kamelfreund.de>
 346 .SH "COPYRIGHT AND LICENSE"
 347 .IX Header "COPYRIGHT AND LICENSE"
 348 Copyright 2002 by Janek Schleicher
 349 .PP
 350 Copyright 2007\-2009 by Alexandr Ciornii, <http://chorny.net/>
 351 .PP
 352 This library is free software; you can redistribute it and/or modify
 353 it under the same terms as Perl itself.