1#@!#!123s

32759 1#@!#!123s
: / home / .cpan / build / Test-Warnings-0.033-0 / blib / man3 /
Filename : Test::Warnings.3pm
back
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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::Warnings 3"
.TH Test::Warnings 3 "2024-01-23" "perl v5.32.1" "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::Warnings \- Test for warnings and the lack of them
.SH "VERSION"
.IX Header "VERSION"
version 0.033
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Test::More;
\&    use Test::Warnings;
\&
\&    pass(\*(Aqyay!\*(Aq);
\&    done_testing;
.Ve
.PP
emits \s-1TAP:\s0
.PP
.Vb 3
\&    ok 1 \- yay!
\&    ok 2 \- no (unexpected) warnings (via done_testing)
\&    1..2
.Ve
.PP
and:
.PP
.Vb 2
\&    use Test::More tests => 3;
\&    use Test::Warnings 0.005 \*(Aq:all\*(Aq;
\&
\&    pass(\*(Aqyay!\*(Aq);
\&    like(warning { warn "oh noes!" }, qr/^oh noes/, \*(Aqwe warned\*(Aq);
.Ve
.PP
emits \s-1TAP:\s0
.PP
.Vb 4
\&    ok 1 \- yay!
\&    ok 2 \- we warned
\&    ok 3 \- no (unexpected) warnings (via END block)
\&    1..3
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you've ever tried to use Test::NoWarnings to confirm there are no warnings
generated by your tests, combined with the convenience of \f(CW\*(C`done_testing\*(C'\fR to
not have to declare a
test count,
you'll have discovered that these two features do not play well together,
as the test count will be calculated \fIbefore\fR the warnings test is run,
resulting in a \s-1TAP\s0 error. (See \f(CW\*(C`examples/test_nowarnings.pl\*(C'\fR in this
distribution for a demonstration.)
.PP
This module is intended to be used as a drop-in replacement for
Test::NoWarnings: it also adds an extra test, but runs this test \fIbefore\fR
\&\f(CW\*(C`done_testing\*(C'\fR calculates the test count, rather than after.  It does this by
hooking into \f(CW\*(C`done_testing\*(C'\fR as well as via an \f(CW\*(C`END\*(C'\fR block.  You can declare
a plan, or not, and things will still Just Work.
.PP
It is actually equivalent to:
.PP
.Vb 1
\&    use Test::NoWarnings 1.04 \*(Aq:early\*(Aq;
.Ve
.PP
as warnings are still printed normally as they occur.  You are safe, and
enthusiastically encouraged, to perform a global search-replace of the above
with \f(CW\*(C`use Test::Warnings;\*(C'\fR whether or not your tests have a plan.
.PP
It can also be used as a replacement for Test::Warn, if you wish to test
the content of expected warnings; read on to find out how.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions are available for import (not included by default; you
can also get all of them by importing the tag \f(CW\*(C`:all\*(C'\fR):
.ie n .SS """allow_warnings([bool])"" \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0"
.el .SS "\f(CWallow_warnings([bool])\fP \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0"
.IX Subsection "allow_warnings([bool]) - EXPERIMENTAL - MAY BE REMOVED"
When passed a true value, or no value at all, subsequent warnings will not
result in a test failure; when passed a false value, subsequent warnings will
result in a test failure.  Initial value is \f(CW\*(C`false\*(C'\fR.
.PP
When warnings are allowed, any warnings will instead be emitted via
Test::Builder::note.
.ie n .SS """allowing_warnings"" \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0"
.el .SS "\f(CWallowing_warnings\fP \- \s-1EXPERIMENTAL\s0 \- \s-1MAY BE REMOVED\s0"
.IX Subsection "allowing_warnings - EXPERIMENTAL - MAY BE REMOVED"
Returns whether we are currently allowing warnings (set by \f(CW\*(C`allow_warnings\*(C'\fR
as described above).
.ie n .SS """had_no_warnings(<optional test name>)"""
.el .SS "\f(CWhad_no_warnings(<optional test name>)\fP"
.IX Subsection "had_no_warnings(<optional test name>)"
Tests whether there have been any warnings so far, not preceded by an
\&\f(CW\*(C`allowing_warnings\*(C'\fR call.  It is run
automatically at the end of all tests, but can also be called manually at any
time, as often as desired.
.ie n .SS """warnings( { code } )"""
.el .SS "\f(CWwarnings( { code } )\fP"
.IX Subsection "warnings( { code } )"
Given a code block, runs the block and returns a list of all the
(not previously allowed via \f(CW\*(C`allow_warnings\*(C'\fR) warnings issued within.  This
lets you test for the presence of warnings that you not only would \fIallow\fR,
but \fImust\fR be issued.  Testing functions are not provided; given the strings
returned, you can test these yourself using your favourite testing functions,
such as Test::More::is or Test::Deep::cmp_deeply.
.PP
You can use this construct as a replacement for
Test::Warn::warnings_are:
.PP
.Vb 8
\&    is_deeply(
\&        [ warnings { ... } ],
\&        [
\&            \*(Aqwarning message 1\*(Aq,
\&            \*(Aqwarning message 2\*(Aq,
\&        ],
\&        \*(Aqgot expected warnings\*(Aq,
\&    );
.Ve
.PP
or, to replace Test::Warn::warnings_like:
.PP
.Vb 8
\&    cmp_deeply(
\&        [ warnings { ... } ],
\&        bag(    # ordering of messages doesn\*(Aqt matter
\&            re(qr/warning message 1/),
\&            re(qr/warning message 2/),
\&        ),
\&        \*(Aqgot expected warnings (in any order)\*(Aq,
\&    );
.Ve
.PP
Warnings generated by this code block are \fI\s-1NOT\s0\fR propagated further. However,
since they are returned from this function with their filename and line
numbers intact, you can re-issue them yourself immediately after calling
\&\f(CW\*(C`warnings(...)\*(C'\fR, if desired.
.PP
Note that \f(CW\*(C`use Test::Warnings \*(Aqwarnings\*(Aq\*(C'\fR will give you a \f(CW\*(C`warnings\*(C'\fR
subroutine in your namespace (most likely \f(CW\*(C`main\*(C'\fR, if you're writing a test),
so you (or things you load) can't subsequently do \f(CW\*(C`warnings\->import\*(C'\fR \*(--
it will result in the error: \*(L"Not enough arguments for
Test::Warnings::warnings at ..., near \*(R"warnings\->import"".  To work around
this, either use the fully-qualified form (\f(CW\*(C`Test::warnings\*(C'\fR) or make your
calls to the \f(CW\*(C`warnings\*(C'\fR package first.
.ie n .SS """warning( { code } )"""
.el .SS "\f(CWwarning( { code } )\fP"
.IX Subsection "warning( { code } )"
Same as \f(CW\*(C`warnings( { code } )\*(C'\fR, except a scalar is always returned \- the
single warning produced, if there was one, or an arrayref otherwise \*(-- which
can be more convenient to use than \f(CW\*(C`warnings()\*(C'\fR if you are expecting exactly
one warning.
.PP
However, you are advised to capture the result from \f(CW\*(C`warning()\*(C'\fR into a temp
variable so you can dump its value if it doesn't contain what you expect.
e.g. with this test:
.PP
.Vb 5
\&    like(
\&        warning { foo() },
\&        qr/^this is a warning/,
\&        \*(Aqgot a warning from foo()\*(Aq,
\&    );
.Ve
.PP
if you get two warnings (or none) back instead of one, you'll get an
arrayref, which will result in an unhelpful test failure message like:
.PP
.Vb 4
\&    #   Failed test \*(Aqgot a warning from foo()\*(Aq
\&    #   at t/mytest.t line 10.
\&    #                   \*(AqARRAY(0xdeadbeef)\*(Aq
\&    #     doesn\*(Aqt match \*(Aq(?^:^this is a warning)\*(Aq
.Ve
.PP
So instead, change your test to:
.PP
.Vb 6
\&    my $warning = warning { foo() };
\&    like(
\&        $warning,
\&        qr/^this is a warning/,
\&        \*(Aqgot a warning from foo()\*(Aq,
\&    ) or diag \*(Aqgot warning(s): \*(Aq, explain($warning);
.Ve
.SS "allow_patterns"
.IX Subsection "allow_patterns"
.Vb 5
\&  allow_patterns(qr/always allow this warning/);
\&  {
\&    my $temp = allow_patterns(qr/only allow in this scope/, qr/another temporary warning/);
\&    ... stuff ...
\&  }
.Ve
.PP
Given one or more regular expressions, in \f(CW\*(C`qr/.../\*(C'\fR form, add them to the allow-list (warnings will
be emitted with \f(CW\*(C`note\*(C'\fR rather than triggering the warning handler). If the return value is saved in
a local variable, the warning exemption will only be in effect for that local scope (the addition is
reversed at the end of the scope); otherwise, the effect is global.
.SS "disallow_patterns"
.IX Subsection "disallow_patterns"
Given one or more regular expressions, in \f(CW\*(C`qr/.../\*(C'\fR form, remove it from the allow-list. The
pattern must exactly match a pattern previously provided to \*(L"allow_patterns\*(R".
.SH "IMPORT OPTIONS"
.IX Header "IMPORT OPTIONS"
.ie n .SS """:all"""
.el .SS "\f(CW:all\fP"
.IX Subsection ":all"
Imports all functions listed above
.ie n .SS """:no_end_test"""
.el .SS "\f(CW:no_end_test\fP"
.IX Subsection ":no_end_test"
Disables the addition of a \f(CW\*(C`had_no_warnings\*(C'\fR test
via \f(CW\*(C`END\*(C'\fR or \f(CW\*(C`done_testing\*(C'\fR
.ie n .SS """:fail_on_warning"""
.el .SS "\f(CW:fail_on_warning\fP"
.IX Subsection ":fail_on_warning"
When used, fail immediately when an unexempted warning is generated (as opposed to waiting until
\&\*(L"had_no_warnings\*(R" or \f(CW\*(C`done_testing\*(C'\fR is called).
.PP
I recommend you only turn this option on when debugging a test, to see where a surprise warning is coming from,
and rely on the end-of-tests check otherwise.
.ie n .SS """:report_warnings"""
.el .SS "\f(CW:report_warnings\fP"
.IX Subsection ":report_warnings"
When used, \f(CW\*(C`had_no_warnings()\*(C'\fR will print all the unexempted warning content, in case it had been suppressed
earlier by other captures (such as \*(L"stderr_like\*(R" in Test::Output or \*(L"capture\*(R" in Capture::Tiny).
.SH "OTHER OPTIONS"
.IX Header "OTHER OPTIONS"
You can temporarily turn off the failure behaviour of this module, swapping it out for reporting
(see \f(CW\*(C`:report_warnings\*(C'\fR above) with:
.PP
.Vb 1
\&  $ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS} = 1;
.Ve
.PP
This can be useful for working around problematic modules that have warnings in newer Perl versions.
.SH "CAVEATS"
.IX Header "CAVEATS"
Sometimes new warnings can appear in Perl that should \fBnot\fR block
installation \*(-- for example, smartmatch was recently deprecated in
perl 5.17.11, so now any distribution that uses smartmatch and also
tests for warnings cannot be installed under 5.18.0.  You might want to
consider only making warnings fail tests in an author environment \*(-- you can
do this with the if pragma:
.PP
.Vb 1
\&    use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, \*(AqTest::Warnings\*(Aq;
.Ve
.PP
In future versions of this module, when interfaces are added to test the
content of warnings, there will likely be additional sugar available to
indicate that warnings should be checked only in author tests (or \s-1TODO\s0 when
not in author testing), but will still provide exported subs.  Comments are
enthusiastically solicited \- drop me an email, write up an \s-1RT\s0 ticket, or come
by \f(CW\*(C`#perl\-qa\*(C'\fR on irc!
.PP
\&\fBAchtung!\fR  This is not a great idea:
.PP
.Vb 4
\&    sub warning_like(&$;$) {
\&        my ($code, $pattern, $name) = @_;
\&        like( &warning($code), $pattern, $name );
\&    }
\&
\&    warning_like( { ... }, qr/foo/, \*(Aqfoo appears in the warning\*(Aq );
.Ve
.PP
If the code in the \f(CW\*(C`{ ... }\*(C'\fR is going to warn with a stack trace with the
arguments to each subroutine in its call stack (for example via \f(CW\*(C`Carp::cluck\*(C'\fR),
the test name, \*(L"foo appears in the warning\*(R" will itself be matched by the
regex (see \fIexamples/warning_like.t\fR).  Instead, write this:
.PP
.Vb 1
\&  like( warning { ... }, qr/foo/, \*(Aqfoo appears in the warning\*(Aq );
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
If you are using another module that sets its own warning handler (for example Devel::Confess or
diagnostics) your results may be mixed, as those handlers will interfere with this module's
ability to properly detect and capture warnings in their original form.
.SH "TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES)"
.IX Header "TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES)"
.IP "\(bu" 4
\&\f(CW\*(C`allow_warnings(qr/.../)\*(C'\fR \- allow some warnings and not others
.IP "\(bu" 4
more sophisticated handling in subtests \- if we save some state on the
Test::Builder object itself, we can allow warnings in a subtest and then
the state will revert when the subtest ends, as well as check for warnings at
the end of every subtest via \f(CW\*(C`done_testing\*(C'\fR.
.IP "\(bu" 4
sugar for making failures \s-1TODO\s0 when testing outside an author
environment
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Test::NoWarnings
.IP "\(bu" 4
Test::FailWarnings
.IP "\(bu" 4
blogs.perl.org: \s-1YANWT\s0 (Yet Another No-Warnings Tester) <http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-warnings-tester.html>
.IP "\(bu" 4
strictures \- which makes all warnings fatal in tests, hence lessening the need for special warning testing
.IP "\(bu" 4
Test::Warn
.IP "\(bu" 4
Test::Fatal
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted through the \s-1RT\s0 bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings>
(or bug\-Test\-Warnings@rt.cpan.org <mailto:bug-Test-Warnings@rt.cpan.org>).
.PP
There is also a mailing list available for users of this distribution, at
<http://lists.perl.org/list/perl\-qa.html>.
.PP
There is also an irc channel available for users of this distribution, at
\&\f(CW\*(C`#perl\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR <irc://irc.perl.org/#perl-qa>.
.PP
I am also usually active on irc, as 'ether' at \f(CW\*(C`irc.perl.org\*(C'\fR and \f(CW\*(C`irc.libera.chat\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Karen Etheridge <ether@cpan.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Graham Knop <haarg@haarg.org>
.IP "\(bu" 4
A. Sinan Unur <nanis@cpan.org>
.IP "\(bu" 4
Leon Timmermans <fawaka@gmail.com>
.IP "\(bu" 4
Tina Mueller <cpan2@tinita.de>
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013 by Karen Etheridge.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.