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.026
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
175 Sometimes new warnings can appear in Perl that should not block
176 installation -- for example, smartmatch was recently deprecated in perl
177 5.17.11, so now any distribution that uses smartmatch and also tests
178 for warnings cannot be installed under 5.18.0. You might want to
179 consider only making warnings fail tests in an author environment --
180 you can do this with the if pragma:
181 use if $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING}, 'Test::Warnings';
183 In future versions of this module, when interfaces are added to test
185 the content of warnings, there will likely be additional sugar
186 available to indicate that warnings should be checked only in author
187 tests (or TODO when not in author testing), but will still provide
188 exported subs. Comments are enthusiastically solicited - drop me an
189 email, write up an RT ticket, or come by "#perl-qa" on irc!
190 Achtung! This is not a great idea:
192 sub warning_like(&$;$) {
194 my ($code, $pattern, $name) = @_;
195 like( &warning($code), $pattern, $name );
196 }
197 warning_like( { ... }, qr/foo/, 'foo appears in the warning' );
199 If the code in the "{ ... }" is going to warn with a stack trace with
201 the arguments to each subroutine in its call stack (for example via
202 "Carp::cluck"), the test name, "foo appears in the warning" will itself
203 be matched by the regex (see examples/warning_like.t). Instead, write
204 this:
205 like( warning { ... }, qr/foo/, 'foo appears in the warning' );
207
209 · "allow_warnings(qr/.../)" - allow some warnings and not others
210 · more sophisticated handling in subtests - if we save some state on
212 the Test::Builder object itself, we can allow warnings in a subtest
213 and then the state will revert when the subtest ends, as well as
214 check for warnings at the end of every subtest via "done_testing".
215 · sugar for making failures TODO when testing outside an author
217 environment
218
220 · Test::NoWarnings
221 · Test::FailWarnings
223 · blogs.perl.org: YANWT (Yet Another No-Warnings Tester)
225 <http://blogs.perl.org/users/ether/2013/03/yanwt-yet-another-no-
226 warnings-tester.html>
227 · strictures - which makes all warnings fatal in tests, hence
229 lessening
230 the need for special warning testing
232 · Test::Warn
234 · Test::Fatal
236
238 Bugs may be submitted through the RT bug tracker
239 <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Warnings> (or
240 bug-Test-Warnings@rt.cpan.org <mailto:bug-Test-Warnings@rt.cpan.org>).
241 There is also a mailing list available for users of this distribution,
243 at <http://lists.perl.org/list/perl-qa.html>.
244 There is also an irc channel available for users of this distribution,
246 at <irc://irc.perl.org/#perl-qa>.
247 I am also usually active on irc, as 'ether' at "irc.perl.org".
249
251 Karen Etheridge <ether@cpan.org>
252
254 A. Sinan Unur <nanis@cpan.org>
255
257 This software is copyright (c) 2013 by Karen Etheridge.
258 This is free software; you can redistribute it and/or modify it under
260 the same terms as the Perl 5 programming language system itself.
261perl v5.28.0 2016-01-27 Test::Warnings(3)