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.030
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 ":report_warnings"
184 When used, "had_no_warnings()" will print all the unexempted warning
185 content, in case it had been suppressed earlier by other captures (such
186 as "stderr_like" in Test::Output or "capture" in Capture::Tiny).
187
189 Sometimes new warnings can appear in Perl that should not block
190 installation -- for example, smartmatch was recently deprecated in perl
191 5.17.11, so now any distribution that uses smartmatch and also tests
192 for warnings cannot be installed under 5.18.0. You might want to
193 consider only making warnings fail tests in an author environment --
194 you can do this with the if pragma:
195 use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, 'Test::Warnings';
197 In future versions of this module, when interfaces are added to test
199 the content of warnings, there will likely be additional sugar
200 available to indicate that warnings should be checked only in author
201 tests (or TODO when not in author testing), but will still provide
202 exported subs. Comments are enthusiastically solicited - drop me an
203 email, write up an RT ticket, or come by "#perl-qa" on irc!
204 Achtung! This is not a great idea:
206 sub warning_like(&$;$) {
208 my ($code, $pattern, $name) = @_;
209 like( &warning($code), $pattern, $name );
210 }
211 warning_like( { ... }, qr/foo/, 'foo appears in the warning' );
213 If the code in the "{ ... }" is going to warn with a stack trace with
215 the arguments to each subroutine in its call stack (for example via
216 "Carp::cluck"), the test name, "foo appears in the warning" will itself
217 be matched by the regex (see examples/warning_like.t). Instead, write
218 this:
219 like( warning { ... }, qr/foo/, 'foo appears in the warning' );
221
223 · "allow_warnings(qr/.../)" - allow some warnings and not others
224 · more sophisticated handling in subtests - if we save some state on
226 the Test::Builder object itself, we can allow warnings in a subtest
227 and then the state will revert when the subtest ends, as well as
228 check for warnings at the end of every subtest via "done_testing".
229 · sugar for making failures TODO when testing outside an author
231 environment
232
234 · Test::NoWarnings
235 · Test::FailWarnings
237 · blogs.perl.org: YANWT (Yet Another No-Warnings Tester)
239 <http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-
240 warnings-tester.html>
241 · strictures - which makes all warnings fatal in tests, hence
243 lessening the need for special warning testing
244 · Test::Warn
246 · Test::Fatal
248
250 Bugs may be submitted through the RT bug tracker
251 <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings> (or
252 bug-Test-Warnings@rt.cpan.org <mailto:bug-Test-Warnings@rt.cpan.org>).
253 There is also a mailing list available for users of this distribution,
255 at <http://lists.perl.org/list/perl-qa.html>.
256 There is also an irc channel available for users of this distribution,
258 at "#perl" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
259 I am also usually active on irc, as 'ether' at "irc.perl.org".
261
263 Karen Etheridge <ether@cpan.org>
264
266 · Graham Knop <haarg@haarg.org>
267 · A. Sinan Unur <nanis@cpan.org>
269 · Leon Timmermans <fawaka@gmail.com>
271 · Tina Mueller <cpan2@tinita.de>
273
275 This software is copyright (c) 2013 by Karen Etheridge.
276 This is free software; you can redistribute it and/or modify it under
278 the same terms as the Perl 5 programming language system itself.
279perl v5.32.0 2020-07-28 Test::Warnings(3)