Debian Codegraph @

upstream/debian-unstable/man3/Test::Builder.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test::Builder 3perl"
58 .TH Test::Builder 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test::Builder \- Backend for building test libraries
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& package My::Test::Module;
69 \& use base \*(AqTest::Builder::Module\*(Aq;
70 \&
71 \& my $CLASS = _\|_PACKAGE_\|_;
72 \&
73 \& sub ok {
74 \& my($test, $name) = @_;
75 \& my $tb = $CLASS\->builder;
76 \&
77 \& $tb\->ok($test, $name);
78 \& }
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 Test::Simple and Test::More have proven to be popular testing modules,
83 but they're not always flexible enough. Test::Builder provides a
84 building block upon which to write your own test libraries \fIwhich can
85 work together\fR.
86 .SS Construction
87 .IX Subsection "Construction"
88 .IP \fBnew\fR 4
89 .IX Item "new"
90 .Vb 1
91 \& my $Test = Test::Builder\->new;
92 .Ve
93 .Sp
94 Returns a Test::Builder object representing the current state of the
95 test.
96 .Sp
97 Since you only run one test per program \f(CW\*(C`new\*(C'\fR always returns the same
98 Test::Builder object. No matter how many times you call \f(CWnew()\fR, you're
99 getting the same object. This is called a singleton. This is done so that
100 multiple modules share such global information as the test counter and
101 where test output is going.
102 .Sp
103 If you want a completely new Test::Builder object different from the
104 singleton, use \f(CW\*(C`create\*(C'\fR.
105 .IP \fBcreate\fR 4
106 .IX Item "create"
107 .Vb 1
108 \& my $Test = Test::Builder\->create;
109 .Ve
110 .Sp
111 Ok, so there can be more than one Test::Builder object and this is how
112 you get it. You might use this instead of \f(CWnew()\fR if you're testing
113 a Test::Builder based module, but otherwise you probably want \f(CW\*(C`new\*(C'\fR.
114 .Sp
115 \&\fBNOTE\fR: the implementation is not complete. \f(CW\*(C`level\*(C'\fR, for example, is still
116 shared by \fBall\fR Test::Builder objects, even ones created using this method.
117 Also, the method name may change in the future.
118 .IP \fBsubtest\fR 4
119 .IX Item "subtest"
120 .Vb 1
121 \& $builder\->subtest($name, \e&subtests, @args);
122 .Ve
123 .Sp
124 See documentation of \f(CW\*(C`subtest\*(C'\fR in Test::More.
125 .Sp
126 \&\f(CW\*(C`subtest\*(C'\fR also, and optionally, accepts arguments which will be passed to the
127 subtests reference.
128 .IP \fBname\fR 4
129 .IX Item "name"
130 .Vb 1
131 \& diag $builder\->name;
132 .Ve
133 .Sp
134 Returns the name of the current builder. Top level builders default to \f(CW$0\fR
135 (the name of the executable). Child builders are named via the \f(CW\*(C`child\*(C'\fR
136 method. If no name is supplied, will be named "Child of \f(CW$parent\fR\->name".
137 .IP \fBreset\fR 4
138 .IX Item "reset"
139 .Vb 1
140 \& $Test\->reset;
141 .Ve
142 .Sp
143 Reinitializes the Test::Builder singleton to its original state.
144 Mostly useful for tests run in persistent environments where the same
145 test might be run multiple times in the same process.
146 .SS "Setting up tests"
147 .IX Subsection "Setting up tests"
148 These methods are for setting up tests and declaring how many there
149 are. You usually only want to call one of these methods.
150 .IP \fBplan\fR 4
151 .IX Item "plan"
152 .Vb 3
153 \& $Test\->plan(\*(Aqno_plan\*(Aq);
154 \& $Test\->plan( skip_all => $reason );
155 \& $Test\->plan( tests => $num_tests );
156 .Ve
157 .Sp
158 A convenient way to set up your tests. Call this and Test::Builder
159 will print the appropriate headers and take the appropriate actions.
160 .Sp
161 If you call \f(CWplan()\fR, don't call any of the other methods below.
162 .IP \fBexpected_tests\fR 4
163 .IX Item "expected_tests"
164 .Vb 2
165 \& my $max = $Test\->expected_tests;
166 \& $Test\->expected_tests($max);
167 .Ve
168 .Sp
169 Gets/sets the number of tests we expect this test to run and prints out
170 the appropriate headers.
171 .IP \fBno_plan\fR 4
172 .IX Item "no_plan"
173 .Vb 1
174 \& $Test\->no_plan;
175 .Ve
176 .Sp
177 Declares that this test will run an indeterminate number of tests.
178 .IP \fBdone_testing\fR 4
179 .IX Item "done_testing"
180 .Vb 2
181 \& $Test\->done_testing();
182 \& $Test\->done_testing($num_tests);
183 .Ve
184 .Sp
185 Declares that you are done testing, no more tests will be run after this point.
186 .Sp
187 If a plan has not yet been output, it will do so.
188 .Sp
189 \&\f(CW$num_tests\fR is the number of tests you planned to run. If a numbered
190 plan was already declared, and if this contradicts, a failing test
191 will be run to reflect the planning mistake. If \f(CW\*(C`no_plan\*(C'\fR was declared,
192 this will override.
193 .Sp
194 If \f(CWdone_testing()\fR is called twice, the second call will issue a
195 failing test.
196 .Sp
197 If \f(CW$num_tests\fR is omitted, the number of tests run will be used, like
198 no_plan.
199 .Sp
200 \&\f(CWdone_testing()\fR is, in effect, used when you'd want to use \f(CW\*(C`no_plan\*(C'\fR, but
201 safer. You'd use it like so:
202 .Sp
203 .Vb 2
204 \& $Test\->ok($a == $b);
205 \& $Test\->done_testing();
206 .Ve
207 .Sp
208 Or to plan a variable number of tests:
209 .Sp
210 .Vb 4
211 \& for my $test (@tests) {
212 \& $Test\->ok($test);
213 \& }
214 \& $Test\->done_testing(scalar @tests);
215 .Ve
216 .IP \fBhas_plan\fR 4
217 .IX Item "has_plan"
218 .Vb 1
219 \& $plan = $Test\->has_plan
220 .Ve
221 .Sp
222 Find out whether a plan has been defined. \f(CW$plan\fR is either \f(CW\*(C`undef\*(C'\fR (no plan
223 has been set), \f(CW\*(C`no_plan\*(C'\fR (indeterminate # of tests) or an integer (the number
224 of expected tests).
225 .IP \fBskip_all\fR 4
226 .IX Item "skip_all"
227 .Vb 2
228 \& $Test\->skip_all;
229 \& $Test\->skip_all($reason);
230 .Ve
231 .Sp
232 Skips all the tests, using the given \f(CW$reason\fR. Exits immediately with 0.
233 .IP \fBexported_to\fR 4
234 .IX Item "exported_to"
235 .Vb 2
236 \& my $pack = $Test\->exported_to;
237 \& $Test\->exported_to($pack);
238 .Ve
239 .Sp
240 Tells Test::Builder what package you exported your functions to.
241 .Sp
242 This method isn't terribly useful since modules which share the same
243 Test::Builder object might get exported to different packages and only
244 the last one will be honored.
245 .SS "Running tests"
246 .IX Subsection "Running tests"
247 These actually run the tests, analogous to the functions in Test::More.
248 .PP
249 They all return true if the test passed, false if the test failed.
250 .PP
251 \&\f(CW$name\fR is always optional.
252 .IP \fBok\fR 4
253 .IX Item "ok"
254 .Vb 1
255 \& $Test\->ok($test, $name);
256 .Ve
257 .Sp
258 Your basic test. Pass if \f(CW$test\fR is true, fail if \f(CW$test\fR is false. Just
259 like Test::Simple's \f(CWok()\fR.
260 .IP \fBis_eq\fR 4
261 .IX Item "is_eq"
262 .Vb 1
263 \& $Test\->is_eq($got, $expected, $name);
264 .Ve
265 .Sp
266 Like Test::More's \f(CWis()\fR. Checks if \f(CW\*(C`$got eq $expected\*(C'\fR. This is the
267 string version.
268 .Sp
269 \&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR.
270 .IP \fBis_num\fR 4
271 .IX Item "is_num"
272 .Vb 1
273 \& $Test\->is_num($got, $expected, $name);
274 .Ve
275 .Sp
276 Like Test::More's \f(CWis()\fR. Checks if \f(CW\*(C`$got == $expected\*(C'\fR. This is the
277 numeric version.
278 .Sp
279 \&\f(CW\*(C`undef\*(C'\fR only ever matches another \f(CW\*(C`undef\*(C'\fR.
280 .IP \fBisnt_eq\fR 4
281 .IX Item "isnt_eq"
282 .Vb 1
283 \& $Test\->isnt_eq($got, $dont_expect, $name);
284 .Ve
285 .Sp
286 Like Test::More's \f(CWisnt()\fR. Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR. This is
287 the string version.
288 .IP \fBisnt_num\fR 4
289 .IX Item "isnt_num"
290 .Vb 1
291 \& $Test\->isnt_num($got, $dont_expect, $name);
292 .Ve
293 .Sp
294 Like Test::More's \f(CWisnt()\fR. Checks if \f(CW\*(C`$got ne $dont_expect\*(C'\fR. This is
295 the numeric version.
296 .IP \fBlike\fR 4
297 .IX Item "like"
298 .Vb 2
299 \& $Test\->like($thing, qr/$regex/, $name);
300 \& $Test\->like($thing, \*(Aq/$regex/\*(Aq, $name);
301 .Ve
302 .Sp
303 Like Test::More's \f(CWlike()\fR. Checks if \f(CW$thing\fR matches the given \f(CW$regex\fR.
304 .IP \fBunlike\fR 4
305 .IX Item "unlike"
306 .Vb 2
307 \& $Test\->unlike($thing, qr/$regex/, $name);
308 \& $Test\->unlike($thing, \*(Aq/$regex/\*(Aq, $name);
309 .Ve
310 .Sp
311 Like Test::More's \f(CWunlike()\fR. Checks if \f(CW$thing\fR \fBdoes not match\fR the
312 given \f(CW$regex\fR.
313 .IP \fBcmp_ok\fR 4
314 .IX Item "cmp_ok"
315 .Vb 1
316 \& $Test\->cmp_ok($thing, $type, $that, $name);
317 .Ve
318 .Sp
319 Works just like Test::More's \f(CWcmp_ok()\fR.
320 .Sp
321 .Vb 1
322 \& $Test\->cmp_ok($big_num, \*(Aq!=\*(Aq, $other_big_num);
323 .Ve
324 .SS "Other Testing Methods"
325 .IX Subsection "Other Testing Methods"
326 These are methods which are used in the course of writing a test but are not themselves tests.
327 .IP \fBBAIL_OUT\fR 4
328 .IX Item "BAIL_OUT"
329 .Vb 1
330 \& $Test\->BAIL_OUT($reason);
331 .Ve
332 .Sp
333 Indicates to the Test::Harness that things are going so badly all
334 testing should terminate. This includes running any additional test
335 scripts.
336 .Sp
337 It will exit with 255.
338 .IP \fBskip\fR 4
339 .IX Item "skip"
340 .Vb 2
341 \& $Test\->skip;
342 \& $Test\->skip($why);
343 .Ve
344 .Sp
345 Skips the current test, reporting \f(CW$why\fR.
346 .IP \fBtodo_skip\fR 4
347 .IX Item "todo_skip"
348 .Vb 2
349 \& $Test\->todo_skip;
350 \& $Test\->todo_skip($why);
351 .Ve
352 .Sp
353 Like \f(CWskip()\fR, only it will declare the test as failing and TODO. Similar
354 to
355 .Sp
356 .Vb 1
357 \& print "not ok $tnum # TODO $why\en";
358 .Ve
359 .SS "Test building utility methods"
360 .IX Subsection "Test building utility methods"
361 These methods are useful when writing your own test methods.
362 .IP \fBmaybe_regex\fR 4
363 .IX Item "maybe_regex"
364 .Vb 2
365 \& $Test\->maybe_regex(qr/$regex/);
366 \& $Test\->maybe_regex(\*(Aq/$regex/\*(Aq);
367 .Ve
368 .Sp
369 This method used to be useful back when Test::Builder worked on Perls
370 before 5.6 which didn't have qr//. Now its pretty useless.
371 .Sp
372 Convenience method for building testing functions that take regular
373 expressions as arguments.
374 .Sp
375 Takes a quoted regular expression produced by \f(CW\*(C`qr//\*(C'\fR, or a string
376 representing a regular expression.
377 .Sp
378 Returns a Perl value which may be used instead of the corresponding
379 regular expression, or \f(CW\*(C`undef\*(C'\fR if its argument is not recognized.
380 .Sp
381 For example, a version of \f(CWlike()\fR, sans the useful diagnostic messages,
382 could be written as:
383 .Sp
384 .Vb 7
385 \& sub laconic_like {
386 \& my ($self, $thing, $regex, $name) = @_;
387 \& my $usable_regex = $self\->maybe_regex($regex);
388 \& die "expecting regex, found \*(Aq$regex\*(Aq\en"
389 \& unless $usable_regex;
390 \& $self\->ok($thing =~ m/$usable_regex/, $name);
391 \& }
392 .Ve
393 .IP \fBis_fh\fR 4
394 .IX Item "is_fh"
395 .Vb 1
396 \& my $is_fh = $Test\->is_fh($thing);
397 .Ve
398 .Sp
399 Determines if the given \f(CW$thing\fR can be used as a filehandle.
400 .SS "Test style"
401 .IX Subsection "Test style"
402 .IP \fBlevel\fR 4
403 .IX Item "level"
404 .Vb 1
405 \& $Test\->level($how_high);
406 .Ve
407 .Sp
408 How far up the call stack should \f(CW$Test\fR look when reporting where the
409 test failed.
410 .Sp
411 Defaults to 1.
412 .Sp
413 Setting \f(CW$Test::Builder::Level\fR overrides. This is typically useful
414 localized:
415 .Sp
416 .Vb 2
417 \& sub my_ok {
418 \& my $test = shift;
419 \&
420 \& local $Test::Builder::Level = $Test::Builder::Level + 1;
421 \& $TB\->ok($test);
422 \& }
423 .Ve
424 .Sp
425 To be polite to other functions wrapping your own you usually want to increment \f(CW$Level\fR rather than set it to a constant.
426 .IP \fBuse_numbers\fR 4
427 .IX Item "use_numbers"
428 .Vb 1
429 \& $Test\->use_numbers($on_or_off);
430 .Ve
431 .Sp
432 Whether or not the test should output numbers. That is, this if true:
433 .Sp
434 .Vb 3
435 \& ok 1
436 \& ok 2
437 \& ok 3
438 .Ve
439 .Sp
440 or this if false
441 .Sp
442 .Vb 3
443 \& ok
444 \& ok
445 \& ok
446 .Ve
447 .Sp
448 Most useful when you can't depend on the test output order, such as
449 when threads or forking is involved.
450 .Sp
451 Defaults to on.
452 .IP \fBno_diag\fR 4
453 .IX Item "no_diag"
454 .Vb 1
455 \& $Test\->no_diag($no_diag);
456 .Ve
457 .Sp
458 If set true no diagnostics will be printed. This includes calls to
459 \&\f(CWdiag()\fR.
460 .IP \fBno_ending\fR 4
461 .IX Item "no_ending"
462 .Vb 1
463 \& $Test\->no_ending($no_ending);
464 .Ve
465 .Sp
466 Normally, Test::Builder does some extra diagnostics when the test
467 ends. It also changes the exit code as described below.
468 .Sp
469 If this is true, none of that will be done.
470 .IP \fBno_header\fR 4
471 .IX Item "no_header"
472 .Vb 1
473 \& $Test\->no_header($no_header);
474 .Ve
475 .Sp
476 If set to true, no "1..N" header will be printed.
477 .SS Output
478 .IX Subsection "Output"
479 Controlling where the test output goes.
480 .PP
481 It's ok for your test to change where STDOUT and STDERR point to,
482 Test::Builder's default output settings will not be affected.
483 .IP \fBdiag\fR 4
484 .IX Item "diag"
485 .Vb 1
486 \& $Test\->diag(@msgs);
487 .Ve
488 .Sp
489 Prints out the given \f(CW@msgs\fR. Like \f(CW\*(C`print\*(C'\fR, arguments are simply
490 appended together.
491 .Sp
492 Normally, it uses the \f(CWfailure_output()\fR handle, but if this is for a
493 TODO test, the \f(CWtodo_output()\fR handle is used.
494 .Sp
495 Output will be indented and marked with a # so as not to interfere
496 with test output. A newline will be put on the end if there isn't one
497 already.
498 .Sp
499 We encourage using this rather than calling print directly.
500 .Sp
501 Returns false. Why? Because \f(CWdiag()\fR is often used in conjunction with
502 a failing test (\f(CW\*(C`ok() || diag()\*(C'\fR) it "passes through" the failure.
503 .Sp
504 .Vb 1
505 \& return ok(...) || diag(...);
506 .Ve
507 .IP \fBnote\fR 4
508 .IX Item "note"
509 .Vb 1
510 \& $Test\->note(@msgs);
511 .Ve
512 .Sp
513 Like \f(CWdiag()\fR, but it prints to the \f(CWoutput()\fR handle so it will not
514 normally be seen by the user except in verbose mode.
515 .IP \fBexplain\fR 4
516 .IX Item "explain"
517 .Vb 1
518 \& my @dump = $Test\->explain(@msgs);
519 .Ve
520 .Sp
521 Will dump the contents of any references in a human readable format.
522 Handy for things like...
523 .Sp
524 .Vb 1
525 \& is_deeply($have, $want) || diag explain $have;
526 .Ve
527 .Sp
528 or
529 .Sp
530 .Vb 1
531 \& is_deeply($have, $want) || note explain $have;
532 .Ve
533 .IP \fBoutput\fR 4
534 .IX Item "output"
535 .PD 0
536 .IP \fBfailure_output\fR 4
537 .IX Item "failure_output"
538 .IP \fBtodo_output\fR 4
539 .IX Item "todo_output"
540 .PD
541 .Vb 4
542 \& my $filehandle = $Test\->output;
543 \& $Test\->output($filehandle);
544 \& $Test\->output($filename);
545 \& $Test\->output(\e$scalar);
546 .Ve
547 .Sp
548 These methods control where Test::Builder will print its output.
549 They take either an open \f(CW$filehandle\fR, a \f(CW$filename\fR to open and write to
550 or a \f(CW$scalar\fR reference to append to. It will always return a \f(CW$filehandle\fR.
551 .Sp
552 \&\fBoutput\fR is where normal "ok/not ok" test output goes.
553 .Sp
554 Defaults to STDOUT.
555 .Sp
556 \&\fBfailure_output\fR is where diagnostic output on test failures and
557 \&\f(CWdiag()\fR goes. It is normally not read by Test::Harness and instead is
558 displayed to the user.
559 .Sp
560 Defaults to STDERR.
561 .Sp
562 \&\f(CW\*(C`todo_output\*(C'\fR is used instead of \f(CWfailure_output()\fR for the
563 diagnostics of a failing TODO test. These will not be seen by the
564 user.
565 .Sp
566 Defaults to STDOUT.
567 .IP reset_outputs 4
568 .IX Item "reset_outputs"
569 .Vb 1
570 \& $tb\->reset_outputs;
571 .Ve
572 .Sp
573 Resets all the output filehandles back to their defaults.
574 .IP carp 4
575 .IX Item "carp"
576 .Vb 1
577 \& $tb\->carp(@message);
578 .Ve
579 .Sp
580 Warns with \f(CW@message\fR but the message will appear to come from the
581 point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR).
582 .IP croak 4
583 .IX Item "croak"
584 .Vb 1
585 \& $tb\->croak(@message);
586 .Ve
587 .Sp
588 Dies with \f(CW@message\fR but the message will appear to come from the
589 point where the original test function was called (\f(CW\*(C`$tb\->caller\*(C'\fR).
590 .SS "Test Status and Info"
591 .IX Subsection "Test Status and Info"
592 .IP \fBno_log_results\fR 4
593 .IX Item "no_log_results"
594 This will turn off result long-term storage. Calling this method will make
595 \&\f(CW\*(C`details\*(C'\fR and \f(CW\*(C`summary\*(C'\fR useless. You may want to use this if you are running
596 enough tests to fill up all available memory.
597 .Sp
598 .Vb 1
599 \& Test::Builder\->new\->no_log_results();
600 .Ve
601 .Sp
602 There is no way to turn it back on.
603 .IP \fBcurrent_test\fR 4
604 .IX Item "current_test"
605 .Vb 2
606 \& my $curr_test = $Test\->current_test;
607 \& $Test\->current_test($num);
608 .Ve
609 .Sp
610 Gets/sets the current test number we're on. You usually shouldn't
611 have to set this.
612 .Sp
613 If set forward, the details of the missing tests are filled in as 'unknown'.
614 if set backward, the details of the intervening tests are deleted. You
615 can erase history if you really want to.
616 .IP \fBis_passing\fR 4
617 .IX Item "is_passing"
618 .Vb 1
619 \& my $ok = $builder\->is_passing;
620 .Ve
621 .Sp
622 Indicates if the test suite is currently passing.
623 .Sp
624 More formally, it will be false if anything has happened which makes
625 it impossible for the test suite to pass. True otherwise.
626 .Sp
627 For example, if no tests have run \f(CWis_passing()\fR will be true because
628 even though a suite with no tests is a failure you can add a passing
629 test to it and start passing.
630 .Sp
631 Don't think about it too much.
632 .IP \fBsummary\fR 4
633 .IX Item "summary"
634 .Vb 1
635 \& my @tests = $Test\->summary;
636 .Ve
637 .Sp
638 A simple summary of the tests so far. True for pass, false for fail.
639 This is a logical pass/fail, so todos are passes.
640 .Sp
641 Of course, test #1 is \f(CW$tests\fR[0], etc...
642 .IP \fBdetails\fR 4
643 .IX Item "details"
644 .Vb 1
645 \& my @tests = $Test\->details;
646 .Ve
647 .Sp
648 Like \f(CWsummary()\fR, but with a lot more detail.
649 .Sp
650 .Vb 7
651 \& $tests[$test_num \- 1] =
652 \& { \*(Aqok\*(Aq => is the test considered a pass?
653 \& actual_ok => did it literally say \*(Aqok\*(Aq?
654 \& name => name of the test (if any)
655 \& type => type of test (if any, see below).
656 \& reason => reason for the above (if any)
657 \& };
658 .Ve
659 .Sp
660 \&'ok' is true if Test::Harness will consider the test to be a pass.
661 .Sp
662 \&'actual_ok' is a reflection of whether or not the test literally
663 printed 'ok' or 'not ok'. This is for examining the result of 'todo'
664 tests.
665 .Sp
666 \&'name' is the name of the test.
667 .Sp
668 \&'type' indicates if it was a special test. Normal tests have a type
669 of ''. Type can be one of the following:
670 .Sp
671 .Vb 4
672 \& skip see skip()
673 \& todo see todo()
674 \& todo_skip see todo_skip()
675 \& unknown see below
676 .Ve
677 .Sp
678 Sometimes the Test::Builder test counter is incremented without it
679 printing any test output, for example, when \f(CWcurrent_test()\fR is changed.
680 In these cases, Test::Builder doesn't know the result of the test, so
681 its type is 'unknown'. These details for these tests are filled in.
682 They are considered ok, but the name and actual_ok is left \f(CW\*(C`undef\*(C'\fR.
683 .Sp
684 For example "not ok 23 \- hole count # TODO insufficient donuts" would
685 result in this structure:
686 .Sp
687 .Vb 7
688 \& $tests[22] = # 23 \- 1, since arrays start from 0.
689 \& { ok => 1, # logically, the test passed since its todo
690 \& actual_ok => 0, # in absolute terms, it failed
691 \& name => \*(Aqhole count\*(Aq,
692 \& type => \*(Aqtodo\*(Aq,
693 \& reason => \*(Aqinsufficient donuts\*(Aq
694 \& };
695 .Ve
696 .IP \fBtodo\fR 4
697 .IX Item "todo"
698 .Vb 2
699 \& my $todo_reason = $Test\->todo;
700 \& my $todo_reason = $Test\->todo($pack);
701 .Ve
702 .Sp
703 If the current tests are considered "TODO" it will return the reason,
704 if any. This reason can come from a \f(CW$TODO\fR variable or the last call
705 to \f(CWtodo_start()\fR.
706 .Sp
707 Since a TODO test does not need a reason, this function can return an
708 empty string even when inside a TODO block. Use \f(CW\*(C`$Test\->in_todo\*(C'\fR
709 to determine if you are currently inside a TODO block.
710 .Sp
711 \&\f(CWtodo()\fR is about finding the right package to look for \f(CW$TODO\fR in. It's
712 pretty good at guessing the right package to look at. It first looks for
713 the caller based on \f(CW\*(C`$Level + 1\*(C'\fR, since \f(CWtodo()\fR is usually called inside
714 a test function. As a last resort it will use \f(CWexported_to()\fR.
715 .Sp
716 Sometimes there is some confusion about where \f(CWtodo()\fR should be looking
717 for the \f(CW$TODO\fR variable. If you want to be sure, tell it explicitly
718 what \f(CW$pack\fR to use.
719 .IP \fBfind_TODO\fR 4
720 .IX Item "find_TODO"
721 .Vb 2
722 \& my $todo_reason = $Test\->find_TODO();
723 \& my $todo_reason = $Test\->find_TODO($pack);
724 .Ve
725 .Sp
726 Like \f(CWtodo()\fR but only returns the value of \f(CW$TODO\fR ignoring
727 \&\f(CWtodo_start()\fR.
728 .Sp
729 Can also be used to set \f(CW$TODO\fR to a new value while returning the
730 old value:
731 .Sp
732 .Vb 1
733 \& my $old_reason = $Test\->find_TODO($pack, 1, $new_reason);
734 .Ve
735 .IP \fBin_todo\fR 4
736 .IX Item "in_todo"
737 .Vb 1
738 \& my $in_todo = $Test\->in_todo;
739 .Ve
740 .Sp
741 Returns true if the test is currently inside a TODO block.
742 .IP \fBtodo_start\fR 4
743 .IX Item "todo_start"
744 .Vb 2
745 \& $Test\->todo_start();
746 \& $Test\->todo_start($message);
747 .Ve
748 .Sp
749 This method allows you declare all subsequent tests as TODO tests, up until
750 the \f(CW\*(C`todo_end\*(C'\fR method has been called.
751 .Sp
752 The \f(CW\*(C`TODO:\*(C'\fR and \f(CW$TODO\fR syntax is generally pretty good about figuring out
753 whether or not we're in a TODO test. However, often we find that this is not
754 possible to determine (such as when we want to use \f(CW$TODO\fR but
755 the tests are being executed in other packages which can't be inferred
756 beforehand).
757 .Sp
758 Note that you can use this to nest "todo" tests
759 .Sp
760 .Vb 6
761 \& $Test\->todo_start(\*(Aqworking on this\*(Aq);
762 \& # lots of code
763 \& $Test\->todo_start(\*(Aqworking on that\*(Aq);
764 \& # more code
765 \& $Test\->todo_end;
766 \& $Test\->todo_end;
767 .Ve
768 .Sp
769 This is generally not recommended, but large testing systems often have weird
770 internal needs.
771 .Sp
772 We've tried to make this also work with the TODO: syntax, but it's not
773 guaranteed and its use is also discouraged:
774 .Sp
775 .Vb 9
776 \& TODO: {
777 \& local $TODO = \*(AqWe have work to do!\*(Aq;
778 \& $Test\->todo_start(\*(Aqworking on this\*(Aq);
779 \& # lots of code
780 \& $Test\->todo_start(\*(Aqworking on that\*(Aq);
781 \& # more code
782 \& $Test\->todo_end;
783 \& $Test\->todo_end;
784 \& }
785 .Ve
786 .Sp
787 Pick one style or another of "TODO" to be on the safe side.
788 .ie n .IP """todo_end""" 4
789 .el .IP \f(CWtodo_end\fR 4
790 .IX Item "todo_end"
791 .Vb 1
792 \& $Test\->todo_end;
793 .Ve
794 .Sp
795 Stops running tests as "TODO" tests. This method is fatal if called without a
796 preceding \f(CW\*(C`todo_start\*(C'\fR method call.
797 .IP \fBcaller\fR 4
798 .IX Item "caller"
799 .Vb 3
800 \& my $package = $Test\->caller;
801 \& my($pack, $file, $line) = $Test\->caller;
802 \& my($pack, $file, $line) = $Test\->caller($height);
803 .Ve
804 .Sp
805 Like the normal \f(CWcaller()\fR, except it reports according to your \f(CWlevel()\fR.
806 .Sp
807 \&\f(CW$height\fR will be added to the \f(CWlevel()\fR.
808 .Sp
809 If \f(CWcaller()\fR winds up off the top of the stack it report the highest context.
810 .SH "EXIT CODES"
811 .IX Header "EXIT CODES"
812 If all your tests passed, Test::Builder will exit with zero (which is
813 normal). If anything failed it will exit with how many failed. If
814 you run less (or more) tests than you planned, the missing (or extras)
815 will be considered failures. If no tests were ever run Test::Builder
816 will throw a warning and exit with 255. If the test died, even after
817 having successfully completed all its tests, it will still be
818 considered a failure and will exit with 255.
819 .PP
820 So the exit codes are...
821 .PP
822 .Vb 3
823 \& 0 all tests successful
824 \& 255 test died or all passed but wrong # of tests run
825 \& any other number how many failed (including missing or extras)
826 .Ve
827 .PP
828 If you fail more than 254 tests, it will be reported as 254.
829 .SH THREADS
830 .IX Header "THREADS"
831 In perl 5.8.1 and later, Test::Builder is thread-safe. The test number is
832 shared by all threads. This means if one thread sets the test number using
833 \&\f(CWcurrent_test()\fR they will all be effected.
834 .PP
835 While versions earlier than 5.8.1 had threads they contain too many
836 bugs to support.
837 .PP
838 Test::Builder is only thread-aware if threads.pm is loaded \fIbefore\fR
839 Test::Builder.
840 .PP
841 You can directly disable thread support with one of the following:
842 .PP
843 .Vb 1
844 \& $ENV{T2_NO_IPC} = 1
845 .Ve
846 .PP
847 or
848 .PP
849 .Vb 1
850 \& no Test2::IPC;
851 .Ve
852 .PP
853 or
854 .PP
855 .Vb 1
856 \& Test2::API::test2_ipc_disable()
857 .Ve
858 .SH MEMORY
859 .IX Header "MEMORY"
860 An informative hash, accessible via \f(CWdetails()\fR, is stored for each
861 test you perform. So memory usage will scale linearly with each test
862 run. Although this is not a problem for most test suites, it can
863 become an issue if you do large (hundred thousands to million)
864 combinatorics tests in the same run.
865 .PP
866 In such cases, you are advised to either split the test file into smaller
867 ones, or use a reverse approach, doing "normal" (code) compares and
868 triggering \f(CWfail()\fR should anything go unexpected.
869 .PP
870 Future versions of Test::Builder will have a way to turn history off.
871 .SH EXAMPLES
872 .IX Header "EXAMPLES"
873 CPAN can provide the best examples. Test::Simple, Test::More,
874 Test::Exception and Test::Differences all use Test::Builder.
875 .SH "SEE ALSO"
876 .IX Header "SEE ALSO"
877 .SS INTERNALS
878 .IX Subsection "INTERNALS"
879 Test2, Test2::API
880 .SS LEGACY
881 .IX Subsection "LEGACY"
882 Test::Simple, Test::More
883 .SS EXTERNAL
884 .IX Subsection "EXTERNAL"
885 Test::Harness
886 .SH AUTHORS
887 .IX Header "AUTHORS"
888 Original code by chromatic, maintained by Michael G Schwern
889 <[email protected]>
890 .SH MAINTAINERS
891 .IX Header "MAINTAINERS"
892 .IP "Chad Granum <[email protected]>" 4
893 .IX Item "Chad Granum <[email protected]>"
894 .SH COPYRIGHT
895 .IX Header "COPYRIGHT"
896 Copyright 2002\-2008 by chromatic <[email protected]> and
897 Michael G Schwern <[email protected]>.
898 .PP
899 This program is free software; you can redistribute it and/or
900 modify it under the same terms as Perl itself.
901 .PP
902 See <https://dev.perl.org/licenses/>