1Test::Builder(3pm) Perl Programmers Reference Guide Test::Builder(3pm)
2
6 Test::Builder - Backend for building test libraries
7
9 package My::Test::Module;
10 use Test::Builder;
11 require Exporter;
12 @ISA = qw(Exporter);
13 @EXPORT = qw(ok);
14 my $Test = Test::Builder->new;
16 $Test->output('my_logfile');
17 sub import {
19 my($self) = shift;
20 my $pack = caller;
21 $Test->exported_to($pack);
23 $Test->plan(@_);
24 $self->export_to_level(1, $self, 'ok');
26 }
27 sub ok {
29 my($test, $name) = @_;
30 $Test->ok($test, $name);
32 }
33
35 Test::Simple and Test::More have proven to be popular testing modules,
36 but they're not always flexible enough. Test::Builder provides the a
37 building block upon which to write your own test libraries which can
38 work together.
39 Construction
41 new
43 my $Test = Test::Builder->new;
44 Returns a Test::Builder object representing the current state of
46 the test.
47 Since you only run one test per program "new" always returns the
49 same Test::Builder object. No matter how many times you call
50 new(), you're getting the same object. This is called a singleton.
51 This is done so that multiple modules share such global information
52 as the test counter and where test output is going.
53 If you want a completely new Test::Builder object different from
55 the singleton, use "create".
56 create
58 my $Test = Test::Builder->create;
59 Ok, so there can be more than one Test::Builder object and this is
61 how you get it. You might use this instead of "new()" if you're
62 testing a Test::Builder based module, but otherwise you probably
63 want "new".
64 NOTE: the implementation is not complete. "level", for example, is
66 still shared amongst all Test::Builder objects, even ones created
67 using this method. Also, the method name may change in the future.
68 reset
70 $Test->reset;
71 Reinitializes the Test::Builder singleton to its original state.
73 Mostly useful for tests run in persistent environments where the
74 same test might be run multiple times in the same process.
75 Setting up tests
77 These methods are for setting up tests and declaring how many there
79 are. You usually only want to call one of these methods.
80 exported_to
82 my $pack = $Test->exported_to;
83 $Test->exported_to($pack);
84 Tells Test::Builder what package you exported your functions to.
86 This is important for getting TODO tests right.
87 plan
89 $Test->plan('no_plan');
90 $Test->plan( skip_all => $reason );
91 $Test->plan( tests => $num_tests );
92 A convenient way to set up your tests. Call this and Test::Builder
94 will print the appropriate headers and take the appropriate
95 actions.
96 If you call plan(), don't call any of the other methods below.
98 expected_tests
100 my $max = $Test->expected_tests;
101 $Test->expected_tests($max);
102 Gets/sets the # of tests we expect this test to run and prints out
104 the appropriate headers.
105 no_plan
107 $Test->no_plan;
108 Declares that this test will run an indeterminate # of tests.
110 has_plan
112 $plan = $Test->has_plan
113 Find out whether a plan has been defined. $plan is either "undef"
115 (no plan has been set), "no_plan" (indeterminate # of tests) or an
116 integer (the number of expected tests).
117 skip_all
119 $Test->skip_all;
120 $Test->skip_all($reason);
121 Skips all the tests, using the given $reason. Exits immediately
123 with 0.
124 Running tests
126 These actually run the tests, analogous to the functions in Test::More.
128 $name is always optional.
130 ok
132 $Test->ok($test, $name);
133 Your basic test. Pass if $test is true, fail if $test is false.
135 Just like Test::Simple's ok().
136 is_eq
138 $Test->is_eq($got, $expected, $name);
139 Like Test::More's is(). Checks if $got eq $expected. This is the
141 string version.
142 is_num
144 $Test->is_num($got, $expected, $name);
145 Like Test::More's is(). Checks if $got == $expected. This is the
147 numeric version.
148 isnt_eq
150 $Test->isnt_eq($got, $dont_expect, $name);
151 Like Test::More's isnt(). Checks if $got ne $dont_expect. This is
153 the string version.
154 isnt_num
156 $Test->is_num($got, $dont_expect, $name);
157 Like Test::More's isnt(). Checks if $got ne $dont_expect. This is
159 the numeric version.
160 like
162 $Test->like($this, qr/$regex/, $name);
163 $Test->like($this, '/$regex/', $name);
164 Like Test::More's like(). Checks if $this matches the given
166 $regex.
167 You'll want to avoid qr// if you want your tests to work before
169 5.005.
170 unlike
172 $Test->unlike($this, qr/$regex/, $name);
173 $Test->unlike($this, '/$regex/', $name);
174 Like Test::More's unlike(). Checks if $this does not match the
176 given $regex.
177 maybe_regex
179 $Test->maybe_regex(qr/$regex/);
180 $Test->maybe_regex('/$regex/');
181 Convenience method for building testing functions that take regular
183 expressions as arguments, but need to work before perl 5.005.
184 Takes a quoted regular expression produced by qr//, or a string
186 representing a regular expression.
187 Returns a Perl value which may be used instead of the corresponding
189 regular expression, or undef if it's argument is not recognised.
190 For example, a version of like(), sans the useful diagnostic mes‐
192 sages, could be written as:
193 sub laconic_like {
195 my ($self, $this, $regex, $name) = @_;
196 my $usable_regex = $self->maybe_regex($regex);
197 die "expecting regex, found '$regex'\n"
198 unless $usable_regex;
199 $self->ok($this =~ m/$usable_regex/, $name);
200 }
201 cmp_ok
203 $Test->cmp_ok($this, $type, $that, $name);
204 Works just like Test::More's cmp_ok().
206 $Test->cmp_ok($big_num, '!=', $other_big_num);
208 BAIL_OUT
210 $Test->BAIL_OUT($reason);
211 Indicates to the Test::Harness that things are going so badly all
213 testing should terminate. This includes running any additional
214 test scripts.
215 It will exit with 255.
217 skip
219 $Test->skip;
220 $Test->skip($why);
221 Skips the current test, reporting $why.
223 todo_skip
225 $Test->todo_skip;
226 $Test->todo_skip($why);
227 Like skip(), only it will declare the test as failing and TODO.
229 Similar to
230 print "not ok $tnum # TODO $why\n";
232 Test style
234 level
236 $Test->level($how_high);
237 How far up the call stack should $Test look when reporting where
239 the test failed.
240 Defaults to 1.
242 Setting $Test::Builder::Level overrides. This is typically useful
244 localized:
245 {
247 local $Test::Builder::Level = 2;
248 $Test->ok($test);
249 }
250 use_numbers
252 $Test->use_numbers($on_or_off);
253 Whether or not the test should output numbers. That is, this if
255 true:
256 ok 1
258 ok 2
259 ok 3
260 or this if false
262 ok
264 ok
265 ok
266 Most useful when you can't depend on the test output order, such as
268 when threads or forking is involved.
269 Test::Harness will accept either, but avoid mixing the two styles.
271 Defaults to on.
273 no_diag
275 $Test->no_diag($no_diag);
276 If set true no diagnostics will be printed. This includes calls to
278 diag().
279 no_ending
281 $Test->no_ending($no_ending);
282 Normally, Test::Builder does some extra diagnostics when the test
284 ends. It also changes the exit code as described below.
285 If this is true, none of that will be done.
287 no_header
289 $Test->no_header($no_header);
290 If set to true, no "1..N" header will be printed.
292 Output
294 Controlling where the test output goes.
296 It's ok for your test to change where STDOUT and STDERR point to,
298 Test::Builder's default output settings will not be affected.
299 diag
301 $Test->diag(@msgs);
302 Prints out the given @msgs. Like "print", arguments are simply
304 appended together.
305 Normally, it uses the failure_output() handle, but if this is for a
307 TODO test, the todo_output() handle is used.
308 Output will be indented and marked with a # so as not to interfere
310 with test output. A newline will be put on the end if there isn't
311 one already.
312 We encourage using this rather than calling print directly.
314 Returns false. Why? Because diag() is often used in conjunction
316 with a failing test ("ok() ⎪⎪ diag()") it "passes through" the
317 failure.
318 return ok(...) ⎪⎪ diag(...);
320 _print_diag
322 $Test->_print_diag(@msg);
323 Like _print, but prints to the current diagnostic filehandle.
325 output
327 $Test->output($fh);
328 $Test->output($file);
329 Where normal "ok/not ok" test output should go.
331 Defaults to STDOUT.
333 failure_output
335 $Test->failure_output($fh);
336 $Test->failure_output($file);
337 Where diagnostic output on test failures and diag() should go.
339 Defaults to STDERR.
341 todo_output
343 $Test->todo_output($fh);
344 $Test->todo_output($file);
345 Where diagnostics about todo test failures and diag() should go.
347 Defaults to STDOUT.
349 Test Status and Info
351 current_test
353 my $curr_test = $Test->current_test;
354 $Test->current_test($num);
355 Gets/sets the current test number we're on. You usually shouldn't
357 have to set this.
358 If set forward, the details of the missing tests are filled in as
360 'unknown'. if set backward, the details of the intervening tests
361 are deleted. You can erase history if you really want to.
362 summary
364 my @tests = $Test->summary;
365 A simple summary of the tests so far. True for pass, false for
367 fail. This is a logical pass/fail, so todos are passes.
368 Of course, test #1 is $tests[0], etc...
370 details
372 my @tests = $Test->details;
373 Like summary(), but with a lot more detail.
375 $tests[$test_num - 1] =
377 { 'ok' => is the test considered a pass?
378 actual_ok => did it literally say 'ok'?
379 name => name of the test (if any)
380 type => type of test (if any, see below).
381 reason => reason for the above (if any)
382 };
383 'ok' is true if Test::Harness will consider the test to be a pass.
385 'actual_ok' is a reflection of whether or not the test literally
387 printed 'ok' or 'not ok'. This is for examining the result of
388 'todo' tests.
389 'name' is the name of the test.
391 'type' indicates if it was a special test. Normal tests have a
393 type of ''. Type can be one of the following:
394 skip see skip()
396 todo see todo()
397 todo_skip see todo_skip()
398 unknown see below
399 Sometimes the Test::Builder test counter is incremented without it
401 printing any test output, for example, when current_test() is
402 changed. In these cases, Test::Builder doesn't know the result of
403 the test, so it's type is 'unkown'. These details for these tests
404 are filled in. They are considered ok, but the name and actual_ok
405 is left undef.
406 For example "not ok 23 - hole count # TODO insufficient donuts"
408 would result in this structure:
409 $tests[22] = # 23 - 1, since arrays start from 0.
411 { ok => 1, # logically, the test passed since it's todo
412 actual_ok => 0, # in absolute terms, it failed
413 name => 'hole count',
414 type => 'todo',
415 reason => 'insufficient donuts'
416 };
417 todo
419 my $todo_reason = $Test->todo;
420 my $todo_reason = $Test->todo($pack);
421 todo() looks for a $TODO variable in your tests. If set, all tests
423 will be considered 'todo' (see Test::More and Test::Harness for
424 details). Returns the reason (ie. the value of $TODO) if running
425 as todo tests, false otherwise.
426 todo() is about finding the right package to look for $TODO in. It
428 uses the exported_to() package to find it. If that's not set, it's
429 pretty good at guessing the right package to look at based on
430 $Level.
431 Sometimes there is some confusion about where todo() should be
433 looking for the $TODO variable. If you want to be sure, tell it
434 explicitly what $pack to use.
435 caller
437 my $package = $Test->caller;
438 my($pack, $file, $line) = $Test->caller;
439 my($pack, $file, $line) = $Test->caller($height);
440 Like the normal caller(), except it reports according to your
442 level().
443
445 If all your tests passed, Test::Builder will exit with zero (which is
446 normal). If anything failed it will exit with how many failed. If you
447 run less (or more) tests than you planned, the missing (or extras) will
448 be considered failures. If no tests were ever run Test::Builder will
449 throw a warning and exit with 255. If the test died, even after having
450 successfully completed all its tests, it will still be considered a
451 failure and will exit with 255.
452 So the exit codes are...
454 0 all tests successful
456 255 test died or all passed but wrong # of tests run
457 any other number how many failed (including missing or extras)
458 If you fail more than 254 tests, it will be reported as 254.
460
462 In perl 5.8.0 and later, Test::Builder is thread-safe. The test number
463 is shared amongst all threads. This means if one thread sets the test
464 number using current_test() they will all be effected.
465 Test::Builder is only thread-aware if threads.pm is loaded before
467 Test::Builder.
468
470 CPAN can provide the best examples. Test::Simple, Test::More,
471 Test::Exception and Test::Differences all use Test::Builder.
472
474 Test::Simple, Test::More, Test::Harness
475
477 Original code by chromatic, maintained by Michael G Schwern <schw‐
478 ern@pobox.com>
479
481 Copyright 2002, 2004 by chromatic <chromatic@wgz.org> and
482 Michael G Schwern <schwern@pobox.com>.
483 This program is free software; you can redistribute it and/or modify it
485 under the same terms as Perl itself.
486 See http://www.perl.com/perl/misc/Artistic.html
488perl v5.8.8 2001-09-21 Test::Builder(3pm)