local-lib5/man/man3/Test::NoWarnings.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 "Test::NoWarnings 3"
 127 .TH Test::NoWarnings 3 "2007-10-20" "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::NoWarnings \- Make sure you didn't emit any warnings while testing
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 For scripts that have no plan
 137 .PP
 138 .Vb 1
 139 \&  use Test::NoWarnings;
 140 .Ve
 141 .PP
 142 that's it, you don't need to do anything else
 143 .PP
 144 For scripts that look like
 145 .PP
 146 .Vb 1
 147 \&  use Test::More tests => x;
 148 .Ve
 149 .PP
 150 change to
 151 .PP
 152 .Vb 2
 153 \&  use Test::More tests => x + 1;
 154 \&  use Test::NoWarnings;
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 In general, your tests shouldn't produce warnings. This modules causes any
 159 warnings to be captured and stored. It automatically adds an extra test that
 160 will run when your script ends to check that there were no warnings. If
 161 there were any warings, the test will give a \*(L"not ok\*(R" and diagnostics of
 162 where, when and what the warning was, including a stack trace of what was
 163 going on when the it occurred.
 164 .PP
 165 If some of your tests \fBare supposed to\fR produce warnings then you should be
 166 capturing and checking them with Test::Warn, that way Test::NoWarnings
 167 will not see them and so not complain.
 168 .PP
 169 The test is run by an \s-1END\s0 block in Test::NoWarnings. It will not be run when
 170 any forked children exit.
 171 .SH "USAGE"
 172 .IX Header "USAGE"
 173 Simply by using the module, you automatically get an extra test at the end
 174 of your script that checks that no warnings were emitted. So just stick
 175 .PP
 176 .Vb 1
 177 \&  use Test::NoWarnings
 178 .Ve
 179 .PP
 180 at the top of your script and continue as normal.
 181 .PP
 182 If you want more control you can invoke the test manually at any time with
 183 \&\f(CW\*(C`had_no_warnings()\*(C'\fR.
 184 .PP
 185 The warnings your test has generated so far are stored in an array. You can
 186 look inside and clear this whenever you want with \f(CW\*(C`warnings()\*(C'\fR and
 187 \&\f(CW\*(C`clear_warnings()\*(C'\fR, however, if you are doing this sort of thing then you
 188 probably want to use Test::Warn in combination with Test::NoWarnings.
 189 .SH "USE vs REQUIRE"
 190 .IX Header "USE vs REQUIRE"
 191 You will almost always want to do
 192 .PP
 193 .Vb 1
 194 \&  use Test::NoWarnings
 195 .Ve
 196 .PP
 197 If you do a \f(CW\*(C`require\*(C'\fR rather than a \f(CW\*(C`use\*(C'\fR, then there will be no automatic
 198 test at the end of your script.
 199 .SH "OUTPUT"
 200 .IX Header "OUTPUT"
 201 If warning is captured during your test then the details will output as part
 202 of the diagnostics. You will get:
 203 .IP "o" 2
 204 .IX Item "o"
 205 the number and name of the test that was executed just before the warning
 206 (if no test had been executed these will be 0 and '')
 207 .IP "o" 2
 208 .IX Item "o"
 209 the message passed to \f(CW\*(C`warn\*(C'\fR,
 210 .IP "o" 2
 211 .IX Item "o"
 212 a full dump of the stack when warn was called, courtesy of the \f(CW\*(C`Carp\*(C'\fR
 213 module
 214 .SH "EXPORTABLE FUNCTIONS"
 215 .IX Header "EXPORTABLE FUNCTIONS"
 216 .SS "\fIhad_no_warnings()\fP"
 217 .IX Subsection "had_no_warnings()"
 218 This checks that there have been warnings emitted by your test scripts.
 219 Usually you will not call this explicitly as it is called automatically when
 220 your script finishes.
 221 .SS "\fIclear_warnings()\fP"
 222 .IX Subsection "clear_warnings()"
 223 This will clear the array of warnings that have been captured. If the array
 224 is empty then a call to \f(CW\*(C`had_no_warnings()\*(C'\fR will produce a pass result.
 225 .SS "\fIwarnings()\fP"
 226 .IX Subsection "warnings()"
 227 This will return the array of warnings captured so far. Each element of this
 228 array is an object containing information about the warning. The following
 229 methods are available on these object.
 230 .IP "\(bu" 2
 231 \&\f(CW$warn\fR\->getMessage
 232 .Sp
 233 Get the message that would been printed by the warning.
 234 .IP "\(bu" 2
 235 \&\f(CW$warn\fR\->getCarp
 236 .Sp
 237 Get a stack trace of what was going on when the warning happened, this stack
 238 trace is just a string generated by the Carp module.
 239 .IP "\(bu" 2
 240 \&\f(CW$warn\fR\->getTrace
 241 .Sp
 242 Get a stack trace object generated by the Devel::StackTrace module. This
 243 will return undef if Devel::StackTrace is not installed.
 244 .IP "\(bu" 2
 245 \&\f(CW$warn\fR\->getTest
 246 .Sp
 247 Get the number of the test that executed before the warning was emitted.
 248 .IP "\(bu" 2
 249 \&\f(CW$warn\fR\->getTestName
 250 .Sp
 251 Get the name of the test that executed before the warning was emitted.
 252 .SH "PITFALLS"
 253 .IX Header "PITFALLS"
 254 When counting your tests for the plan, don't forget to include the test that
 255 runs automatically when your script ends.
 256 .SH "BUGS"
 257 .IX Header "BUGS"
 258 None that I know of.
 259 .SH "HISTORY"
 260 .IX Header "HISTORY"
 261 This was previously known as Test::Warn::None
 262 .SH "SEE ALSO"
 263 .IX Header "SEE ALSO"
 264 Test::Builder, Test::Warn
 265 .SH "AUTHOR"
 266 .IX Header "AUTHOR"
 267 Written by Fergal Daly <fergal@esatclear.ie>.
 268 .SH "COPYRIGHT"
 269 .IX Header "COPYRIGHT"
 270 Copyright 2003 by Fergal Daly <fergal@esatclear.ie>.
 271 .PP
 272 This program is free software and comes with no warranty. It is distributed
 273 under the \s-1LGPL\s0 license
 274 .PP
 275 See the file \fI\s-1LGPL\s0\fR included in this distribution or
 276 \&\fIhttp://www.fsf.org/licenses/licenses.html\fR.