1Test::Most(3) User Contributed Perl Documentation Test::Most(3)
2
6 Test::Most - Most commonly needed test functions and features.
7
9 Version 0.38
10
12 Instead of this:
13 use strict;
15 use warnings;
16 use Test::Exception 0.88;
17 use Test::Differences 0.500;
18 use Test::Deep 0.106;
19 use Test::Warn 0.11;
20 use Test::More tests => 42;
21 You type this:
23 use Test::Most tests => 42;
25
27 Test::Most exists to reduce boilerplate and to make your testing life
28 easier. We provide "one stop shopping" for most commonly used testing
29 modules. In fact, we often require the latest versions so that you get
30 bug fixes through Test::Most and don't have to keep upgrading these
31 modules separately.
32 This module provides you with the most commonly used testing functions,
34 along with automatically turning on strict and warning and gives you a
35 bit more fine-grained control over your test suite.
36 use Test::Most tests => 4, 'die';
38 ok 1, 'Normal calls to ok() should succeed';
40 is 2, 2, '... as should all passing tests';
41 eq_or_diff [3], [4], '... but failing tests should die';
42 ok 4, '... will never get to here';
43 As you can see, the "eq_or_diff" test will fail. Because 'die' is in
45 the import list, the test program will halt at that point.
46 If you do not want strict and warnings enabled, you must explicitly
48 disable them. Thus, you must be explicit about what you want and no
49 longer need to worry about accidentally forgetting them.
50 use Test::Most tests => 4;
52 no strict;
53 no warnings;
54
56 All functions from the following modules will automatically be exported
57 into your namespace:
58 • Test::More
60 • Test::Exception
62 • Test::Differences
64 • Test::Deep
66 • Test::Warn
68 Functions which are optionally exported from any of those modules must
70 be referred to by their fully-qualified name:
71 Test::Deep::render_stack( $var, $stack );
73
75 Several other functions are also automatically exported:
76 "die_on_fail"
78 die_on_fail;
79 is_deeply $foo, bar, '... we throw an exception if this fails';
80 This function, if called, will cause the test program to throw a
82 Test::Most::Exception, effectively halting the test.
83 "bail_on_fail"
85 bail_on_fail;
86 is_deeply $foo, bar, '... we bail out if this fails';
87 This function, if called, will cause the test suite to BAIL_OUT() if
89 any tests fail after it.
90 "restore_fail"
92 die_on_fail;
93 is_deeply $foo, bar, '... we throw an exception if this fails';
94 restore_fail;
96 cmp_bag(\@got, \@bag, '... we will not throw an exception if this fails';
97 This restores the original test failure behavior, so subsequent tests
99 will no longer throw an exception or BAIL_OUT().
100 "set_failure_handler"
102 If you prefer other behavior to 'die_on_fail' or 'bail_on_fail', you
103 can set your own failure handler:
104 set_failure_handler( sub {
106 my $builder = shift;
107 if ( $builder && $builder->{Test_Results}[-1] =~ /critical/ ) {
108 send_admin_email("critical failure in tests");
109 }
110 } );
111 It receives the "Test::Builder" instance as its only argument.
113 Important: Note that if the failing test is the very last test run,
115 then the $builder will likely be undefined. This is an unfortunate
116 side effect of how "Test::Builder" has been designed.
117 "explain"
119 Similar to note(), the output will only be seen by the user by using
120 the "-v" switch with "prove" or reading the raw TAP.
121 Unlike note(), any reference in the argument list is automatically
123 expanded using "Data::Dumper". Thus, instead of this:
124 my $self = Some::Object->new($id);
126 use Data::Dumper;
127 explain 'I was just created', Dumper($self);
128 You can now just do this:
130 my $self = Some::Object->new($id);
132 explain 'I was just created: ', $self;
133 That output will look similar to:
135 I was just created: bless( {
137 'id' => 2,
138 'stack' => []
139 }, 'Some::Object' )
140 Note that the "dumpered" output has the "Data::Dumper" variables
142 $Indent, "Sortkeys" and "Terse" all set to the value of 1 (one). This
143 allows for a much cleaner diagnostic output and at the present time
144 cannot be overridden.
145 Note that Test::More's "explain" acts differently. This "explain" is
147 equivalent to "note explain" in Test::More.
148 "show"
150 Experimental. Just like "explain", but also tries to show you the
151 lexical variable names:
152 my $var = 3;
154 my @array = qw/ foo bar /;
155 show $var, \@array;
156 __END__
157 $var = 3;
158 @array = [
159 'foo',
160 'bar'
161 ];
162 It will show $VAR1, $VAR2 ... $VAR_N for every variable it cannot
164 figure out the variable name to:
165 my @array = qw/ foo bar /;
167 show @array;
168 __END__
169 $VAR1 = 'foo';
170 $VAR2 = 'bar';
171 Note that this relies on Data::Dumper::Names version 0.03 or greater.
173 If this is not present, it will warn and call explain instead. Also,
174 it can only show the names for lexical variables. Globals such as %ENV
175 or "%@" are not accessed via PadWalker and thus cannot be shown. It
176 would be nice to find a workaround for this.
177 "always_explain" and "always_show"
179 These are identical to "explain" and "show", but like Test::More's
180 "diag" function, these will always emit output, regardless of whether
181 or not you're in verbose mode.
182 "all_done"
184 DEPRECATED. Use the new done_testing() (added in Test::More since
185 0.87_01). Instead. We're leaving this in here for a long deprecation
186 cycle. After a while, we might even start warning.
187 If the plan is specified as "defer_plan", you may call &all_done at the
189 end of the test with an optional test number. This lets you set the
190 plan without knowing the plan before you run the tests.
191 If you call it without a test number, the tests will still fail if you
193 don't get to the end of the test. This is useful if you don't want to
194 specify a plan but the tests exit unexpectedly. For example, the
195 following would pass with "no_plan" but fails with "all_done".
196 use Test::More 'defer_plan';
198 ok 1;
199 exit;
200 ok 2;
201 all_done;
202 See "Deferred plans" for more information.
204
206 The following will be exported only if requested:
207 "timeit"
209 Prototype: timeit(&;$)
210 This function will warn if "Time::HiRes" is not installed. The test
212 will still be run, but no timing information will be displayed.
213 use Test::Most 'timeit';
215 timeit { is expensive_function(), $some_value, $message }
216 "expensive_function()";
217 timeit { is expensive_function(), $some_value, $message };
218 "timeit" accepts a code reference and an optional message. After the
220 test is run, will "explain" the time of the function using
221 "Time::HiRes". If a message is supplied, it will be formatted as:
222 sprintf "$message: took %s seconds" => $time;
224 Otherwise, it will be formatted as:
226 sprintf "$filename line $line: took %s seconds" => $time;
228
230 Sometimes you want your test suite to throw an exception or BAIL_OUT()
231 if a test fails. In order to provide maximum flexibility, there are
232 three ways to accomplish each of these.
233 Import list
235 use Test::Most 'die', tests => 7;
236 use Test::Most qw< no_plan bail >;
237 If "die" or "bail" is anywhere in the import list, the test
239 program/suite will throw a "Test::Most::Exception" or BAIL_OUT() as
240 appropriate the first time a test fails. Calling "restore_fail"
241 anywhere in the test program will restore the original behavior (not
242 throwing an exception or bailing out).
243 Functions
245 use Test::Most 'no_plan';
246 ok $bar, 'The test suite will continue if this passes';
247 die_on_fail;
249 is_deeply $foo, bar, '... we throw an exception if this fails';
250 restore_fail;
252 ok $baz, 'The test suite will continue if this passes';
253 The "die_on_fail" and "bail_on_fail" functions will automatically set
255 the desired behavior at runtime.
256 Environment variables
258 DIE_ON_FAIL=1 prove t/
259 BAIL_ON_FAIL=1 prove t/
260 If the "DIE_ON_FAIL" or "BAIL_ON_FAIL" environment variables are true,
262 any tests which use "Test::Most" will throw an exception or call
263 BAIL_OUT on test failure.
264
266 Moose
267 It used to be that this module would produce a warning when used with
268 Moose:
269 Prototype mismatch: sub main::blessed ($) vs none
271 This was because Test::Deep exported a blessed() function by default,
273 but its prototype did not match the Moose version's prototype. We now
274 exclude the Test::Deep version by default. If you need it, you can call
275 the fully-qualified version or request it on the command line:
276 use Test::Most 'blessed';
278 Note that as of version 0.34, "reftype" is also excluded from
280 "Test::Deep"'s import list. This was causing issues with people trying
281 to use "Scalar::Util"'s "reftype" function.
282 Excluding Test Modules
284 Sometimes you want a exclude a particular test module. For example,
285 Test::Deep, when used with Moose, produces the following warning:
286 Prototype mismatch: sub main::blessed ($) vs none
288 You can exclude this with by adding the module to the import list with
290 a '-' symbol in front:
291 use Test::Most tests => 42, '-Test::Deep';
293 See
295 <https://rt.cpan.org/Ticket/Display.html?id=54362&results=e73ff63c5bf9ba0f796efdba5773cf3f>
296 for more information.
297 Excluding Test Symbols
299 Sometimes you don't want to exclude an entire test module, but just a
300 particular symbol that is causing issues You can exclude the symbol(s)
301 in the standard way, by specifying the symbol in the import list with a
302 '!' in front:
303 use Test::Most tests => 42, '!throws_ok';
305 Deferred plans
307 DEPRECATED and will be removed in some future release of this module.
308 Using "defer_plan" will carp(). Use done_testing() from Test::More
309 instead.
310 use Test::Most qw<defer_plan>;
312 use My::Tests;
313 my $test_count = My::Tests->run;
314 all_done($test_count);
315 Sometimes it's difficult to know the plan up front, but you can
317 calculate the plan as your tests run. As a result, you want to defer
318 the plan until the end of the test. Typically, the best you can do is
319 this:
320 use Test::More 'no_plan';
322 use My::Tests;
323 My::Tests->run;
324 But when you do that, "Test::Builder" merely asserts that the number of
326 tests you ran is the number of tests. Until now, there was no way of
327 asserting that the number of tests you expected is the number of tests
328 unless you do so before any tests have run. This fixes that problem.
329 One-stop shopping
331 We generally require the latest stable versions of various test
332 modules. Why? Because they have bug fixes and new features. You
333 don't want to have to keep remembering them, so periodically we'll
334 release new versions of Test::Most just for bug fixes.
335 "use ok"
337 We do not bundle Test::use::ok, though it's been requested. That's
338 because "use_ok" is broken, but Test::use::ok is also subtly broken
339 (and a touch harder to fix). See
340 <http://use.perl.org/~Ovid/journal/39859> for more information.
341 If you want to test if you can use a module, just use it. If it fails,
343 the test will still fail and that's the desired result.
344
346 People want more control over their test suites. Sometimes when you
347 see hundreds of tests failing and whizzing by, you want the test suite
348 to simply halt on the first failure. This module gives you that
349 control.
350 As for the reasons for the four test modules chosen, I ran code over a
352 local copy of the CPAN to find the most commonly used testing modules.
353 Here's the top twenty as of January 2010 (the numbers are different
354 because we're now counting distributions which use a given module
355 rather than simply the number of times a module is used).
356 1 Test::More 14111
358 2 Test 1736
359 3 Test::Exception 744
360 4 Test::Simple 331
361 5 Test::Pod 328
362 6 Test::Pod::Coverage 274
363 7 Test::Perl::Critic 248
364 8 Test::Base 228
365 9 Test::NoWarnings 155
366 10 Test::Distribution 142
367 11 Test::Kwalitee 138
368 12 Test::Deep 128
369 13 Test::Warn 127
370 14 Test::Differences 102
371 15 Test::Spelling 101
372 16 Test::MockObject 87
373 17 Test::Builder::Tester 84
374 18 Test::WWW::Mechanize::Catalyst 79
375 19 Test::UseAllModules 63
376 20 Test::YAML::Meta 61
377 Test::Most is number 24 on that list, if you're curious. See
379 <http://blogs.perl.org/users/ovid/2010/01/most-popular-testing-modules---january-2010.html>.
380 The modules chosen seemed the best fit for what "Test::Most" is trying
382 to do. As of 0.02, we've added Test::Warn by request. It's not in the
383 top ten, but it's a great and useful module.
384
386 Curtis Poe, "<ovid at cpan.org>"
387
389 Please report any bugs or feature requests to "bug-test-extended at
390 rt.cpan.org", or through the web interface at
391 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Most>. I will be
392 notified, and then you'll automatically be notified of progress on your
393 bug as I make changes.
394
396 You can find documentation for this module with the perldoc command.
397 perldoc Test::Most
399 You can also look for information at:
401 • RT: CPAN's request tracker
403 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Most>
405 • AnnoCPAN: Annotated CPAN documentation
407 <http://annocpan.org/dist/Test-Most>
409 • CPAN Ratings
411 <http://cpanratings.perl.org/d/Test-Most>
413 • Search CPAN
415 <http://search.cpan.org/dist/Test-Most>
417
419 Deferred plans
420 Sometimes you don't know the number of tests you will run when you use
421 "Test::More". The plan() function allows you to delay specifying the
422 plan, but you must still call it before the tests are run. This is an
423 error:
424 use Test::More;
426 my $tests = 0;
428 foreach my $test (
429 my $count = run($test); # assumes tests are being run
430 $tests += $count;
431 }
432 plan($tests);
433 The way around this is typically to use 'no_plan' and when the tests
435 are done, "Test::Builder" merely sets the plan to the number of tests
436 run. We'd like for the programmer to specify this number instead of
437 letting "Test::Builder" do it. However, "Test::Builder" internals are
438 a bit difficult to work with, so we're delaying this feature.
439 Cleaner skip()
441 if ( $some_condition ) {
442 skip $message, $num_tests;
443 }
444 else {
445 # run those tests
446 }
447 That would be cleaner and I might add it if enough people want it.
449
451 Because of how Perl handles arguments, and because diagnostics are not
452 really part of the Test Anything Protocol, what actually happens
453 internally is that we note that a test has failed and we throw an
454 exception or bail out as soon as the next test is called (but before it
455 runs). This means that its arguments are automatically evaluated
456 before we can take action:
457 use Test::Most qw<no_plan die>;
459 ok $foo, 'Die if this fails';
461 ok factorial(123456),
462 '... but wait a loooong time before you throw an exception';
463
465 Many thanks to "perl-qa" for arguing about this so much that I just
466 went ahead and did it :)
467 Thanks to Aristotle for suggesting a better way to die or bailout.
469 Thanks to 'swillert' (<http://use.perl.org/~swillert/>) for suggesting
471 a better implementation of my "dumper explain" idea
472 (<http://use.perl.org/~Ovid/journal/37004>).
473
475 Copyright 2008 Curtis Poe, all rights reserved.
476 This program is free software; you can redistribute it and/or modify it
478 under the same terms as Perl itself.
479perl v5.36.0 2023-01-20 Test::Most(3)