.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::NoWarnings 3"
.TH Test::NoWarnings 3 "2011-12-01" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::NoWarnings \- Make sure you didn't emit any warnings while testing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
For scripts that have no plan
.PP
.Vb 1
\&  use Test::NoWarnings;
.Ve
.PP
that's it, you don't need to do anything else
.PP
For scripts that look like
.PP
.Vb 1
\&  use Test::More tests => x;
.Ve
.PP
change to
.PP
.Vb 2
\&  use Test::More tests => x + 1;
\&  use Test::NoWarnings;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In general, your tests shouldn't produce warnings. This modules causes any
warnings to be captured and stored. It automatically adds an extra test that
will run when your script ends to check that there were no warnings. If
there were any warings, the test will give a \*(L"not ok\*(R" and diagnostics of
where, when and what the warning was, including a stack trace of what was
going on when the it occurred.
.PP
If some of your tests \fBare supposed to\fR produce warnings then you should be
capturing and checking them with Test::Warn, that way Test::NoWarnings
will not see them and so not complain.
.PP
The test is run by an \f(CW\*(C`END\*(C'\fR block in Test::NoWarnings. It will not be run
when any forked children exit.
.SH "USAGE"
.IX Header "USAGE"
Simply by using the module, you automatically get an extra test at the end
of your script that checks that no warnings were emitted. So just stick
.PP
.Vb 1
\&  use Test::NoWarnings;
.Ve
.PP
at the top of your script and continue as normal.
.PP
If you want more control you can invoke the test manually at any time with
\&\f(CW\*(C`had_no_warnings\*(C'\fR.
.PP
The warnings your test has generated so far are stored in an array. You can
look inside and clear this whenever you want with \f(CW\*(C`warnings()\*(C'\fR and
\&\f(CW\*(C`clear_warnings\*(C'\fR, however, if you are doing this sort of thing then you
probably want to use Test::Warn in combination with Test::NoWarnings.
.SS "use vs require"
.IX Subsection "use vs require"
You will almost always want to do
.PP
.Vb 1
\&  use Test::NoWarnings
.Ve
.PP
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
test at the end of your script.
.SS "Output"
.IX Subsection "Output"
If warning is captured during your test then the details will output as part
of the diagnostics. You will get:
.IP "o" 2
.IX Item "o"
the number and name of the test that was executed just before the warning
(if no test had been executed these will be 0 and '')
.IP "o" 2
.IX Item "o"
the message passed to \f(CW\*(C`warn\*(C'\fR,
.IP "o" 2
.IX Item "o"
a full dump of the stack when warn was called, courtesy of the \f(CW\*(C`Carp\*(C'\fR
module
.PP
By default, all warning messages will be emitted in one block at the end of
your test script.
.SS "The :early pragma"
.IX Subsection "The :early pragma"
One common complaint from people using Test::NoWarnings is that all of the
warnings are emitted in one go at the end. While this is the safest and
most correct time to emit these diagnostics, it can make debugging these
warnings difficult.
.PP
As of Test::NoWarnings 1.04 you can provide an experimental \f(CW\*(C`:early\*(C'\fR pragma
when loading the module to force warnings to be thrown via diag at the time
that they actually occur.
.PP
.Vb 1
\&  use Test::NoWarnings \*(Aq:early\*(Aq;
.Ve
.PP
As this will cause the diag to be emitted against the previous test and not
the one in which the warning actually occurred it is recommended that the
pragma be turned on only for debugging and left off when not needed.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "had_no_warnings"
.IX Subsection "had_no_warnings"
This checks that there have been warnings emitted by your test scripts.
Usually you will not call this explicitly as it is called automatically when
your script finishes.
.SS "clear_warnings"
.IX Subsection "clear_warnings"
This will clear the array of warnings that have been captured. If the array
is empty then a call to \f(CW\*(C`had_no_warnings()\*(C'\fR will produce a pass result.
.SS "warnings"
.IX Subsection "warnings"
This will return the array of warnings captured so far. Each element of this
array is an object containing information about the warning. The following
methods are available on these object.
.IP "\(bu" 2
\&\f(CW$warn\fR\->getMessage
.Sp
Get the message that would been printed by the warning.
.IP "\(bu" 2
\&\f(CW$warn\fR\->getCarp
.Sp
Get a stack trace of what was going on when the warning happened, this stack
trace is just a string generated by the Carp module.
.IP "\(bu" 2
\&\f(CW$warn\fR\->getTrace
.Sp
Get a stack trace object generated by the Devel::StackTrace module. This
will return undef if Devel::StackTrace is not installed.
.IP "\(bu" 2
\&\f(CW$warn\fR\->getTest
.Sp
Get the number of the test that executed before the warning was emitted.
.IP "\(bu" 2
\&\f(CW$warn\fR\->getTestName
.Sp
Get the name of the test that executed before the warning was emitted.
.SH "PITFALLS"
.IX Header "PITFALLS"
When counting your tests for the plan, don't forget to include the test that
runs automatically when your script ends.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be reported via the \s-1CPAN\s0 bug tracker at
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-NoWarnings>
.PP
For other issues, contact the author.
.SH "HISTORY"
.IX Header "HISTORY"
This was previously known as Test::Warn::None
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::Builder, Test::Warn
.SH "AUTHORS"
.IX Header "AUTHORS"
Fergal Daly <fergal@esatclear.ie>
.PP
Adam Kennedy <adamk@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003 \- 2007 Fergal Daly.
.PP
Some parts copyright 2010 \- 2011 Adam Kennedy.
.PP
This program is free software and comes with no warranty. It is distributed
under the \s-1LGPL\s0 license
.PP
See the file \fI\s-1LGPL\s0\fR included in this distribution or
\&\fIhttp://www.fsf.org/licenses/licenses.html\fR.