Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test::Builder.3pm

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