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.21
10
12 This module provides you with the most commonly used testing functions
13 and gives you a bit more fine-grained control over your test suite.
14 use Test::Most tests => 4, 'die';
16 ok 1, 'Normal calls to ok() should succeed';
18 is 2, 2, '... as should all passing tests';
19 eq_or_diff [3], [4], '... but failing tests should die';
20 ok 4, '... will never get to here';
21 As you can see, the "eq_or_diff" test will fail. Because 'die' is in
23 the import list, the test program will halt at that point.
24
26 All functions from the following modules will automatically be exported
27 into your namespace:
28 · "Test::More"
30 · "Test::Exception"
32 · "Test::Differences"
34 · "Test::Deep"
36 · "Test::Warn"
38 Functions which are optionally exported from any of those modules must
40 be referred to by their fully-qualified name:
41 Test::Deep::render_stack( $var, $stack );
43
45 Several other functions are also automatically exported:
46 "die_on_fail"
48 die_on_fail;
49 is_deeply $foo, bar, '... we throw an exception if this fails';
50 This function, if called, will cause the test program to throw a
52 Test::Most::Exception, effectively halting the test.
53 "bail_on_fail"
55 bail_on_fail;
56 is_deeply $foo, bar, '... we bail out if this fails';
57 This function, if called, will cause the test suite to BAIL_OUT() if
59 any tests fail after it.
60 "restore_fail"
62 die_on_fail;
63 is_deeply $foo, bar, '... we throw an exception if this fails';
64 restore_fail;
66 cmp_bag(\@got, \@bag, '... we will not throw an exception if this fails';
67 This restores the original test failure behavior, so subsequent tests
69 will no longer throw an exception or BAIL_OUT().
70 "set_failure_handler"
72 If you prefer other behavior to 'die_on_fail' or 'bail_on_fail', you
73 can can set your own failure handler:
74 set_failure_handler( sub {
76 my $builder = shift;
77 if ( $builder && $builder->{Test_Results}[-1] =~ /critical/ ) {
78 send_admin_email("critical failure in tests");
79 }
80 } );
81 It receives the "Test::Builder" instance as its only argument.
83 Important: Note that if the failing test is the very last test run,
85 then the $builder will likely be undefined. This is an unfortunate
86 side effect of how "Test::Builder" has been designed.
87 "explain"
89 Similar to "diag()", but only outputs the message if $ENV{TEST_VERBOSE}
90 is set. This is typically set by using the "-v" switch with "prove".
91 Unlike "diag()", any reference in the argument list is autumatically
93 expanded using "Data::Dumper". Thus, instead of this:
94 my $self = Some::Object->new($id);
96 use Data::Dumper;
97 explain 'I was just created', Dumper($self);
98 You can now just do this:
100 my $self = Some::Object->new($id);
102 explain 'I was just created: ', $self;
103 That output will look similar to:
105 I was just created: bless( {
107 'id' => 2,
108 'stack' => []
109 }, 'Some::Object' )
110 Note that the "dumpered" output has the "Data::Dumper" variables
112 $Indent, "Sortkeys" and "Terse" all set to the value of 1 (one). This
113 allows for a much cleaner diagnostic output and at the present time
114 cannot be overridden.
115 Requires "Test::Harness" 3.07 or greater.
117 "show"
119 Experimental. Just like "explain", but also tries to show you the
120 lexical variable names:
121 my $var = 3;
123 my @array = qw/ foo bar /;
124 show $var, \@array;
125 __END__
126 $var = 3;
127 @array = [
128 'foo',
129 'bar'
130 ];
131 It will show $VAR1, $VAR2 ... $VAR_N for every variable it cannot
133 figure out the variable name to:
134 my @array = qw/ foo bar /;
136 show @array;
137 __END__
138 $VAR1 = 'foo';
139 $VAR2 = 'bar';
140 Note that this relies on Data::Dumper::Names version 0.03 or greater.
142 If this is not present, it will warn and call explain instead. Also,
143 it can only show the names for lexical variables. Globals such as %ENV
144 or "%@" are not accessed via PadWalker and thus cannot be shown. It
145 would be nice to find a workaround for this.
146 "all_done"
148 If the plan is specified as "defer_plan", you may call &all_done at the
149 end of the test with an optional test number. This lets you set the
150 plan without knowing the plan before you run the tests.
151 If you call it without a test number, the tests will still fail if you
153 don't get to the end of the test. This is useful if you don't want to
154 specify a plan but the tests exit unexpectedly. For example, the
155 following would pass with "no_plan" but fails with "all_done".
156 use Test::More 'defer_plan';
158 ok 1;
159 exit;
160 ok 2;
161 all_done;
162 See "Deferred plans" for more information.
164
166 Sometimes you want your test suite to throw an exception or BAIL_OUT()
167 if a test fails. In order to provide maximum flexibility, there are
168 three ways to accomplish each of these.
169 Import list
171 use Test::Most 'die', tests => 7;
172 use Test::Most qw< no_plan bail >;
173 If "die" or "bail" is anywhere in the import list, the test
175 program/suite will throw a "Test::Most::Exception" or "BAIL_OUT()" as
176 appropriate the first time a test fails. Calling "restore_fail"
177 anywhere in the test program will restore the original behavior (not
178 throwing an exception or bailing out).
179 Functions
181 use Test::Most 'no_plan;
182 ok $bar, 'The test suite will continue if this passes';
183 die_on_fail;
185 is_deeply $foo, bar, '... we throw an exception if this fails';
186 restore_fail;
188 ok $baz, 'The test suite will continue if this passes';
189 The "die_on_fail" and "bail_on_fail" functions will automatically set
191 the desired behavior at runtime.
192 Deferred plans
194 use Test::Most qw<defer_plan>;
195 use My::Tests;
196 my $test_count = My::Tests->run;
197 all_done($test_count);
198 Sometimes it's difficult to know the plan up front, but you can
200 calculate the plan as your tests run. As a result, you want to defer
201 the plan until the end of the test. Typically, the best you can do is
202 this:
203 use Test::More 'no_plan';
205 use My::Tests;
206 My::Tests->run;
207 But when you do that, "Test::Builder" merely asserts that the number of
209 tests you ran is the number of tests. Until now, there was no way of
210 asserting that the number of tests you expected is the number of tests
211 unless you do so before any tests have run. This fixes that problem.
212 Environment variables
214 DIE_ON_FAIL=1 prove t/
215 BAIL_ON_FAIL=1 prove t/
216 If the "DIE_ON_FAIL" or "BAIL_ON_FAIL" environment variables are true,
218 any tests which use "Test::Most" will throw an exception or call
219 BAIL_OUT on test failure.
220
222 People want more control over their test suites. Sometimes when you
223 see hundreds of tests failing and whizzing by, you want the test suite
224 to simply halt on the first failure. This module gives you that
225 control.
226 As for the reasons for the four test modules chosen, I ran code over a
228 local copy of the CPAN to find the most commonly used testing modules.
229 Here were the top ten (out of 287):
230 Test::More 44461
232 Test 8937
233 Test::Exception 1379
234 Test::Simple 731
235 Test::Base 316
236 Test::Builder::Tester 193
237 Test::NoWarnings 174
238 Test::Differences 146
239 Test::MockObject 139
240 Test::Deep 127
241 The four modules chosen seemed the best fit for what "Test::Most" is
243 trying to do. As of 0.02, we've added Test::Warn by request. It's not
244 in the top ten, but it's a great and useful module.
245
247 Curtis Poe, "<ovid at cpan.org>"
248
250 Please report any bugs or feature requests to "bug-test-extended at
251 rt.cpan.org", or through the web interface at
252 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Most
253 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Most>. I will be
254 notified, and then you'll automatically be notified of progress on your
255 bug as I make changes.
256
258 You can find documentation for this module with the perldoc command.
259 perldoc Test::Most
261 You can also look for information at:
263 · RT: CPAN's request tracker
265 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Most
267 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Most>
268 · AnnoCPAN: Annotated CPAN documentation
270 http://annocpan.org/dist/Test-Most <http://annocpan.org/dist/Test-
272 Most>
273 · CPAN Ratings
275 http://cpanratings.perl.org/d/Test-Most
277 <http://cpanratings.perl.org/d/Test-Most>
278 · Search CPAN
280 http://search.cpan.org/dist/Test-Most
282 <http://search.cpan.org/dist/Test-Most>
283
285 Deferred plans
286 Sometimes you don't know the number of tests you will run when you use
287 "Test::More". The "plan()" function allows you to delay specifying the
288 plan, but you must still call it before the tests are run. This is an
289 error:
290 use Test::More;
292 my $tests = 0;
294 foreach my $test (
295 my $count = run($test); # assumes tests are being run
296 $tests += $count;
297 }
298 plan($tests);
299 The way around this is typically to use 'no_plan' and when the tests
301 are done, "Test::Builder" merely sets the plan to the number of tests
302 run. We'd like for the programmer to specify this number instead of
303 letting "Test::Builder" do it. However, "Test::Builder" internals are
304 a bit difficult to work with, so we're delaying this feature.
305 Cleaner skip()
307 if ( $some_condition ) {
308 skip $message, $num_tests;
309 }
310 else {
311 # run those tests
312 }
313 That would be cleaner and I might add it if enough people want it.
315
317 Because of how Perl handles arguments, and because diagnostics are not
318 really part of the Test Anything Protocol, what actually happens
319 internally is that we note that a test has failed and we throw an
320 exception or bail out as soon as the next test is called (but before it
321 runs). This means that its arguments are automatically evaulated
322 before we can take action:
323 use Test::Most qw<no_plan die>;
325 ok $foo, 'Die if this fails';
327 ok factorial(123456),
328 '... but wait a loooong time before you throw an exception';
329
331 Many thanks to "perl-qa" for arguing about this so much that I just
332 went ahead and did it :)
333 Thanks to Aristotle for suggesting a better way to die or bailout.
335 Thanks to 'swillert' (<http://use.perl.org/~swillert/>) for suggesting
337 a better implementation of my "dumper explain" idea
338 (<http://use.perl.org/~Ovid/journal/37004>).
339
341 Copyright 2008 Curtis Poe, all rights reserved.
342 This program is free software; you can redistribute it and/or modify it
344 under the same terms as Perl itself.
345perl v5.12.0 2010-05-06 Test::Most(3)