1Test::Warnings(3) User Contributed Perl Documentation Test::Warnings(3)
2
6 Test::Warnings - Test for warnings and the lack of them
7
9 version 0.027
10
12 use Test::More;
13 use Test::Warnings;
14 pass('yay!');
16 done_testing;
17 emits TAP:
19 ok 1 - yay!
21 ok 2 - no (unexpected) warnings (via done_testing)
22 1..2
23 and:
25 use Test::More tests => 3;
27 use Test::Warnings 0.005 ':all';
28 pass('yay!');
30 like(warning { warn "oh noes!" }, qr/^oh noes/, 'we warned');
31 emits TAP:
33 ok 1 - yay!
35 ok 2 - we warned
36 ok 3 - no (unexpected) warnings (via END block)
37 1..3
38
40 If you've ever tried to use Test::NoWarnings to confirm there are no
41 warnings generated by your tests, combined with the convenience of
42 "done_testing" to not have to declare a test count, you'll have
43 discovered that these two features do not play well together, as the
44 test count will be calculated before the warnings test is run,
45 resulting in a TAP error. (See "examples/test_nowarnings.pl" in this
46 distribution for a demonstration.)
47 This module is intended to be used as a drop-in replacement for
49 Test::NoWarnings: it also adds an extra test, but runs this test before
50 "done_testing" calculates the test count, rather than after. It does
51 this by hooking into "done_testing" as well as via an "END" block. You
52 can declare a plan, or not, and things will still Just Work.
53 It is actually equivalent to:
55 use Test::NoWarnings 1.04 ':early';
57 as warnings are still printed normally as they occur. You are safe,
59 and enthusiastically encouraged, to perform a global search-replace of
60 the above with "use Test::Warnings;" whether or not your tests have a
61 plan.
62 It can also be used as a replacement for Test::Warn, if you wish to
64 test the content of expected warnings; read on to find out how.
65
67 The following functions are available for import (not included by
68 default; you can also get all of them by importing the tag ":all"):
69 "allow_warnings([bool])" - EXPERIMENTAL - MAY BE REMOVED
71 When passed a true value, or no value at all, subsequent warnings will
72 not result in a test failure; when passed a false value, subsequent
73 warnings will result in a test failure. Initial value is "false".
74 When warnings are allowed, any warnings will instead be emitted via
76 Test::Builder::note.
77 "allowing_warnings" - EXPERIMENTAL - MAY BE REMOVED
79 Returns whether we are currently allowing warnings (set by
80 "allow_warnings" as described above).
81 "had_no_warnings(<optional test name>)"
83 Tests whether there have been any warnings so far, not preceded by an
84 "allowing_warnings" call. It is run automatically at the end of all
85 tests, but can also be called manually at any time, as often as
86 desired.
87 "warnings( { code } )"
89 Given a code block, runs the block and returns a list of all the (not
90 previously allowed via "allow_warnings") warnings issued within. This
91 lets you test for the presence of warnings that you not only would
92 allow, but must be issued. Testing functions are not provided; given
93 the strings returned, you can test these yourself using your favourite
94 testing functions, such as Test::More::is or Test::Deep::cmp_deeply.
95 You can use this construct as a replacement for
97 Test::Warn::warnings_are:
98 is_deeply(
100 [ warnings { ... } ],
101 [
102 'warning message 1',
103 'warning message 2',
104 ],
105 'got expected warnings',
106 );
107 or, to replace Test::Warn::warnings_like:
109 cmp_deeply(
111 [ warnings { ... } ],
112 bag( # ordering of messages doesn't matter
113 re(qr/warning message 1/),
114 re(qr/warning message 2/),
115 ),
116 'got expected warnings (in any order)',
117 );
118 Warnings generated by this code block are NOT propagated further.
120 However, since they are returned from this function with their filename
121 and line numbers intact, you can re-issue them yourself immediately
122 after calling "warnings(...)", if desired.
123 Note that "use Test::Warnings 'warnings'" will give you a "warnings"
125 subroutine in your namespace (most likely "main", if you're writing a
126 test), so you (or things you load) can't subsequently do
127 "warnings->import" -- it will result in the error: "Not enough
128 arguments for Test::Warnings::warnings at ..., near
129 "warnings->import"". To work around this, either use the fully-
130 qualified form ("Test::warnings") or make your calls to the "warnings"
131 package first.
132 "warning( { code } )"
134 Same as "warnings( { code } )", except a scalar is always returned -
135 the single warning produced, if there was one, or an arrayref otherwise
136 -- which can be more convenient to use than "warnings()" if you are
137 expecting exactly one warning.
138 However, you are advised to capture the result from "warning()" into a
140 temp variable so you can dump its value if it doesn't contain what you
141 expect. e.g. with this test:
142 like(
144 warning { foo() },
145 qr/^this is a warning/,
146 'got a warning from foo()',
147 );
148 if you get two warnings (or none) back instead of one, you'll get an
150 arrayref, which will result in an unhelpful test failure message like:
151 # Failed test 'got a warning from foo()'
153 # at t/mytest.t line 10.
154 # 'ARRAY(0xdeadbeef)'
155 # doesn't match '(?^:^this is a warning)'
156 So instead, change your test to:
158 my $warning = warning { foo() };
160 like(
161 $warning,
162 qr/^this is a warning/,
163 'got a warning from foo()',
164 ) or diag 'got warning(s): ', explain($warning);
165
167 ":all"
168 Imports all functions listed above
169 ":no_end_test"
171 Disables the addition of a "had_no_warnings" test via "END" or
172 "done_testing"
173 ":fail_on_warning"
175 When used, fail immediately when an unexempted warning is generated (as
176 opposed to waiting until "had_no_warnings" or "done_testing" is
177 called).
178 I recommend you only turn this option on when debugging a test, to see
180 where a surprise warning is coming from, and rely on the end-of-tests
181 check otherwise.
182
184 Sometimes new warnings can appear in Perl that should not block
185 installation -- for example, smartmatch was recently deprecated in perl
186 5.17.11, so now any distribution that uses smartmatch and also tests
187 for warnings cannot be installed under 5.18.0. You might want to
188 consider only making warnings fail tests in an author environment --
189 you can do this with the if pragma:
190 use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, 'Test::Warnings';
192 In future versions of this module, when interfaces are added to test
194 the content of warnings, there will likely be additional sugar
195 available to indicate that warnings should be checked only in author
196 tests (or TODO when not in author testing), but will still provide
197 exported subs. Comments are enthusiastically solicited - drop me an
198 email, write up an RT ticket, or come by "#perl-qa" on irc!
199 Achtung! This is not a great idea:
201 sub warning_like(&$;$) {
203 my ($code, $pattern, $name) = @_;
204 like( &warning($code), $pattern, $name );
205 }
206 warning_like( { ... }, qr/foo/, 'foo appears in the warning' );
208 If the code in the "{ ... }" is going to warn with a stack trace with
210 the arguments to each subroutine in its call stack (for example via
211 "Carp::cluck"), the test name, "foo appears in the warning" will itself
212 be matched by the regex (see examples/warning_like.t). Instead, write
213 this:
214 like( warning { ... }, qr/foo/, 'foo appears in the warning' );
216
218 · "allow_warnings(qr/.../)" - allow some warnings and not others
219 · more sophisticated handling in subtests - if we save some state on
221 the Test::Builder object itself, we can allow warnings in a subtest
222 and then the state will revert when the subtest ends, as well as
223 check for warnings at the end of every subtest via "done_testing".
224 · sugar for making failures TODO when testing outside an author
226 environment
227
229 · Test::NoWarnings
230 · Test::FailWarnings
232 · blogs.perl.org: YANWT (Yet Another No-Warnings Tester)
234 <http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-
235 warnings-tester.html>
236 · strictures - which makes all warnings fatal in tests, hence
238 lessening the need for special warning testing
239 · Test::Warn
241 · Test::Fatal
243
245 Bugs may be submitted through the RT bug tracker
246 <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings> (or
247 bug-Test-Warnings@rt.cpan.org <mailto:bug-Test-Warnings@rt.cpan.org>).
248 There is also a mailing list available for users of this distribution,
250 at <http://lists.perl.org/list/perl-qa.html>.
251 There is also an irc channel available for users of this distribution,
253 at "#perl" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
254 I am also usually active on irc, as 'ether' at "irc.perl.org".
256
258 Karen Etheridge <ether@cpan.org>
259
261 · A. Sinan Unur <nanis@cpan.org>
262 · Graham Knop <haarg@haarg.org>
264 · Leon Timmermans <fawaka@gmail.com>
266
268 This software is copyright (c) 2013 by Karen Etheridge.
269 This is free software; you can redistribute it and/or modify it under
271 the same terms as the Perl 5 programming language system itself.
272perl v5.30.0 2019-09-28 Test::Warnings(3)