Test::Warnings(3) User Contributed Perl Documentation Test::Warnings(3)
NAME
Test::Warnings - Test for warnings and the lack of them
VERSION
version 0.038
SYNOPSIS
use Test::More;
use Test::Warnings;
pass('yay!');
done_testing;
emits TAP:
ok 1 - yay!
ok 2 - no (unexpected) warnings (via done_testing)
1..2
and:
use Test::More tests => 3;
use Test::Warnings 0.005 ':all';
pass('yay!');
like(warning { warn "oh noes!" }, qr/^oh noes/, 'we warned');
emits TAP:
ok 1 - yay!
ok 2 - we warned
ok 3 - no (unexpected) warnings (via END block)
1..3
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
"done_testing" 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 before the warnings test is run,
resulting in a TAP error. (See "examples/test_nowarnings.pl" in this
distribution for a demonstration.)
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 before
"done_testing" calculates the test count, rather than after. It does
this by hooking into "done_testing" as well as via an "END" block. You
can declare a plan, or not, and things will still Just Work.
It is actually equivalent to:
use Test::NoWarnings 1.04 ':early';
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 "use Test::Warnings;" whether or not your tests have a
plan.
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.
FUNCTIONS
The following functions are available for import (not included by
default; you can also get all of them by importing the tag ":all"):
"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 "false".
When warnings are allowed, any warnings will instead be emitted via
Test::Builder::note.
"allowing_warnings" - EXPERIMENTAL - MAY BE REMOVED
Returns whether we are currently allowing warnings (set by
"allow_warnings" as described above).
"had_no_warnings(<optional test name>)"
Tests whether there have been any warnings so far, not preceded by an
"allowing_warnings" call. It is run automatically at the end of all
tests, but can also be called manually at any time, as often as
desired.
"warnings( { code } )"
Given a code block, runs the block and returns a list of all the (not
previously allowed via "allow_warnings") warnings issued within. This
lets you test for the presence of warnings that you not only would
allow, but must 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.
You can use this construct as a replacement for
Test::Warn::warnings_are:
is_deeply(
[ warnings { ... } ],
[
'warning message 1',
'warning message 2',
],
'got expected warnings',
);
or, to replace Test::Warn::warnings_like:
cmp_deeply(
[ warnings { ... } ],
bag( # ordering of messages doesn't matter
re(qr/warning message 1/),
re(qr/warning message 2/),
),
'got expected warnings (in any order)',
);
Warnings generated by this code block are NOT 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 "warnings(...)", if desired.
Note that "use Test::Warnings 'warnings'" will give you a "warnings"
subroutine in your namespace (most likely "main", if you're writing a
test), so you (or things you load) can't subsequently do
"warnings->import" -- it will result in the error: "Not enough
arguments for Test::Warnings::warnings at ..., near
"warnings->import"". To work around this, either use the fully-
qualified form ("Test::warnings") or make your calls to the "warnings"
package first.
"warning( { code } )"
Same as "warnings( { code } )", 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 "warnings()" if you are
expecting exactly one warning.
However, you are advised to capture the result from "warning()" into a
temp variable so you can dump its value if it doesn't contain what you
expect. e.g. with this test:
like(
warning { foo() },
qr/^this is a warning/,
'got a warning from foo()',
);
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:
# Failed test 'got a warning from foo()'
# at t/mytest.t line 10.
# 'ARRAY(0xdeadbeef)'
# doesn't match '(?^:^this is a warning)'
So instead, change your test to:
my $warning = warning { foo() };
like(
$warning,
qr/^this is a warning/,
'got a warning from foo()',
) or diag 'got warning(s): ', explain($warning);
allow_patterns
allow_patterns(qr/always allow this warning/);
{
my $temp = allow_patterns(qr/only allow in this scope/, qr/another temporary warning/);
... stuff ...
}
Given one or more regular expressions, in "qr/.../" form, add them to
the allow-list (warnings will be emitted with "note" 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.
disallow_patterns
Given one or more regular expressions, in "qr/.../" form, remove it
from the allow-list. The pattern must exactly match a pattern
previously provided to "allow_patterns".
IMPORT OPTIONS
":all"
Imports all functions listed above
":no_end_test"
Disables the addition of a "had_no_warnings" test via "END" or
"done_testing"
":fail_on_warning"
When used, fail immediately when an unexempted warning is generated (as
opposed to waiting until "had_no_warnings" or "done_testing" is
called).
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.
":report_warnings"
When used, "had_no_warnings()" will print all the unexempted warning
content, in case it had been suppressed earlier by other captures (such
as "stderr_like" in Test::Output or "capture" in Capture::Tiny).
OTHER OPTIONS
You can temporarily turn off the failure behaviour of this module,
swapping it out for reporting (see ":report_warnings" above) with:
$ENV{PERL_TEST_WARNINGS_ONLY_REPORT_WARNINGS} = 1;
This can be useful for working around problematic modules that have
warnings in newer Perl versions.
CAVEATS
Sometimes new warnings can appear in Perl that should not 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:
use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, 'Test::Warnings';
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 TODO when not in author testing), but will still provide
exported subs. Comments are enthusiastically solicited - drop me an
email, write up an RT ticket, or come by "#perl-qa" on irc!
Achtung! This is not a great idea:
sub warning_like(&$;$) {
my ($code, $pattern, $name) = @_;
like( &warning($code), $pattern, $name );
}
warning_like( { ... }, qr/foo/, 'foo appears in the warning' );
If the code in the "{ ... }" is going to warn with a stack trace with
the arguments to each subroutine in its call stack (for example via
"Carp::cluck"), the test name, "foo appears in the warning" will itself
be matched by the regex (see examples/warning_like.t). Instead, write
this:
like( warning { ... }, qr/foo/, 'foo appears in the warning' );
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.
TO DO (or: POSSIBLE FEATURES COMING IN FUTURE RELEASES)
o "allow_warnings(qr/.../)" - allow some warnings and not others
o 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 "done_testing".
o sugar for making failures TODO when testing outside an author
environment
SEE ALSO
o Test::NoWarnings(3)
o Test::FailWarnings(3)
o blogs.perl.org: YANWT (Yet Another No-Warnings Tester)
<http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-
warnings-tester.html>
o strictures(3) - which makes all warnings fatal in tests,
hence lessening the need for special warning testing
o Test::Warn(3)
o Test::Fatal(3)
SUPPORT
Bugs may be submitted through the RT 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>).
There is also a mailing list available for users of this distribution,
at <http://lists.perl.org/list/perl-qa.html>.
There is also an irc channel available for users of this distribution,
at "#perl" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
I am also usually active on irc, as 'ether' at "irc.perl.org" and
"irc.libera.chat".
AUTHOR
Karen Etheridge <ether@cpan.org>
CONTRIBUTORS
o Graham Knop <haarg@haarg.org>
o Tina Muller <cpan2@tinita.de>
o A. Sinan Unur <nanis@cpan.org>
o Leon Timmermans <fawaka@gmail.com>
COPYRIGHT AND LICENCE
This software is copyright (c) 2013 by Karen Etheridge.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.34.3 2025-02-02 Test::Warnings(3)
test-warnings 0.38.0 - Generated Thu Sep 4 07:43:13 CDT 2025