mingw/html/lib/Test/Builder.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Test::Builder - Backend for building test libraries</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Test::Builder - Backend for building test libraries</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#construction">Construction</a></li>
  28                 <li><a href="#setting_up_tests">Setting up tests</a></li>
  29                 <li><a href="#running_tests">Running tests</a></li>
  30                 <li><a href="#test_style">Test style</a></li>
  31                 <li><a href="#output">Output</a></li>
  32                 <li><a href="#test_status_and_info">Test Status and Info</a></li>
  33         </ul>
  34
  35         <li><a href="#exit_codes">EXIT CODES</a></li>
  36         <li><a href="#threads">THREADS</a></li>
  37         <li><a href="#examples">EXAMPLES</a></li>
  38         <li><a href="#see_also">SEE ALSO</a></li>
  39         <li><a href="#authors">AUTHORS</a></li>
  40         <li><a href="#copyright">COPYRIGHT</a></li>
  41 </ul>
  42 <!-- INDEX END -->
  43
  44 <hr />
  45 <p>
  46 </p>
  47 <h1><a name="name">NAME</a></h1>
  48 <p>Test::Builder - Backend for building test libraries</p>
  49 <p>
  50 </p>
  51 <hr />
  52 <h1><a name="synopsis">SYNOPSIS</a></h1>
  53 <pre>
  54   package My::Test::Module;
  55   use Test::Builder;
  56   require Exporter;
  57   @ISA = qw(Exporter);
  58   @EXPORT = qw(ok);</pre>
  59 <pre>
  60   my $Test = Test::Builder-&gt;new;
  61   $Test-&gt;output('my_logfile');</pre>
  62 <pre>
  63   sub import {
  64       my($self) = shift;
  65       my $pack = caller;</pre>
  66 <pre>
  67       $Test-&gt;exported_to($pack);
  68       $Test-&gt;plan(@_);</pre>
  69 <pre>
  70       $self-&gt;export_to_level(1, $self, 'ok');
  71   }</pre>
  72 <pre>
  73   sub ok {
  74       my($test, $name) = @_;</pre>
  75 <pre>
  76       $Test-&gt;ok($test, $name);
  77   }</pre>
  78 <p>
  79 </p>
  80 <hr />
  81 <h1><a name="description">DESCRIPTION</a></h1>
  82 <p>Test::Simple and Test::More have proven to be popular testing modules,
  83 but they're not always flexible enough.  Test::Builder provides the a
  84 building block upon which to write your own test libraries <em>which can
  85 work together</em>.</p>
  86 <p>
  87 </p>
  88 <h2><a name="construction">Construction</a></h2>
  89 <dl>
  90 <dt><strong><a name="item_new"><strong>new</strong></a></strong>
  91
  92 <dd>
  93 <pre>
  94   my $Test = Test::Builder-&gt;new;</pre>
  95 </dd>
  96 <dd>
  97 <p>Returns a Test::Builder object representing the current state of the
  98 test.</p>
  99 </dd>
 100 <dd>
 101 <p>Since you only run one test per program <a href="#item_new"><code>new</code></a> always returns the same
 102 Test::Builder object.  No matter how many times you call new(), you're
 103 getting the same object.  This is called a singleton.  This is done so that
 104 multiple modules share such global information as the test counter and
 105 where test output is going.</p>
 106 </dd>
 107 <dd>
 108 <p>If you want a completely new Test::Builder object different from the
 109 singleton, use <a href="#item_create"><code>create</code></a>.</p>
 110 </dd>
 111 <dt><strong><a name="item_create"><strong>create</strong></a></strong>
 112
 113 <dd>
 114 <pre>
 115   my $Test = Test::Builder-&gt;create;</pre>
 116 </dd>
 117 <dd>
 118 <p>Ok, so there can be more than one Test::Builder object and this is how
 119 you get it.  You might use this instead of <a href="#item_new"><code>new()</code></a> if you're testing
 120 a Test::Builder based module, but otherwise you probably want <a href="#item_new"><code>new</code></a>.</p>
 121 </dd>
 122 <dd>
 123 <p><strong>NOTE</strong>: the implementation is not complete.  <a href="#item_level"><code>level</code></a>, for example, is
 124 still shared amongst <strong>all</strong> Test::Builder objects, even ones created using
 125 this method.  Also, the method name may change in the future.</p>
 126 </dd>
 127 <dt><strong><a name="item_reset"><strong>reset</strong></a></strong>
 128
 129 <dd>
 130 <pre>
 131   $Test-&gt;reset;</pre>
 132 </dd>
 133 <dd>
 134 <p>Reinitializes the Test::Builder singleton to its original state.
 135 Mostly useful for tests run in persistent environments where the same
 136 test might be run multiple times in the same process.</p>
 137 </dd>
 138 </dl>
 139 <p>
 140 </p>
 141 <h2><a name="setting_up_tests">Setting up tests</a></h2>
 142 <p>These methods are for setting up tests and declaring how many there
 143 are.  You usually only want to call one of these methods.</p>
 144 <dl>
 145 <dt><strong><a name="item_exported_to"><strong>exported_to</strong></a></strong>
 146
 147 <dd>
 148 <pre>
 149   my $pack = $Test-&gt;exported_to;
 150   $Test-&gt;exported_to($pack);</pre>
 151 </dd>
 152 <dd>
 153 <p>Tells Test::Builder what package you exported your functions to.
 154 This is important for getting TODO tests right.</p>
 155 </dd>
 156 <dt><strong><a name="item_plan"><strong>plan</strong></a></strong>
 157
 158 <dd>
 159 <pre>
 160   $Test-&gt;plan('no_plan');
 161   $Test-&gt;plan( skip_all =&gt; $reason );
 162   $Test-&gt;plan( tests =&gt; $num_tests );</pre>
 163 </dd>
 164 <dd>
 165 <p>A convenient way to set up your tests.  Call this and Test::Builder
 166 will print the appropriate headers and take the appropriate actions.</p>
 167 </dd>
 168 <dd>
 169 <p>If you call plan(), don't call any of the other methods below.</p>
 170 </dd>
 171 <dt><strong><a name="item_expected_tests"><strong>expected_tests</strong></a></strong>
 172
 173 <dd>
 174 <pre>
 175     my $max = $Test-&gt;expected_tests;
 176     $Test-&gt;expected_tests($max);</pre>
 177 </dd>
 178 <dd>
 179 <p>Gets/sets the # of tests we expect this test to run and prints out
 180 the appropriate headers.</p>
 181 </dd>
 182 <dt><strong><a name="item_no_plan"><strong>no_plan</strong></a></strong>
 183
 184 <dd>
 185 <pre>
 186   $Test-&gt;no_plan;</pre>
 187 </dd>
 188 <dd>
 189 <p>Declares that this test will run an indeterminate # of tests.</p>
 190 </dd>
 191 <dt><strong><a name="item_has_plan"><strong>has_plan</strong></a></strong>
 192
 193 <dd>
 194 <pre>
 195   $plan = $Test-&gt;has_plan</pre>
 196 </dd>
 197 <dd>
 198 <p>Find out whether a plan has been defined. $plan is either <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> (no plan has been set), <a href="#item_no_plan"><code>no_plan</code></a> (indeterminate # of tests) or an integer (the number of expected tests).</p>
 199 </dd>
 200 <dt><strong><a name="item_skip_all"><strong>skip_all</strong></a></strong>
 201
 202 <dd>
 203 <pre>
 204   $Test-&gt;skip_all;
 205   $Test-&gt;skip_all($reason);</pre>
 206 </dd>
 207 <dd>
 208 <p>Skips all the tests, using the given $reason.  Exits immediately with 0.</p>
 209 </dd>
 210 </dl>
 211 <p>
 212 </p>
 213 <h2><a name="running_tests">Running tests</a></h2>
 214 <p>These actually run the tests, analogous to the functions in
 215 Test::More.</p>
 216 <p>$name is always optional.</p>
 217 <dl>
 218 <dt><strong><a name="item_ok"><strong>ok</strong></a></strong>
 219
 220 <dd>
 221 <pre>
 222   $Test-&gt;ok($test, $name);</pre>
 223 </dd>
 224 <dd>
 225 <p>Your basic test.  Pass if $test is true, fail if $test is false.  Just
 226 like Test::Simple's ok().</p>
 227 </dd>
 228 <dt><strong><a name="item_is_eq"><strong>is_eq</strong></a></strong>
 229
 230 <dd>
 231 <pre>
 232   $Test-&gt;is_eq($got, $expected, $name);</pre>
 233 </dd>
 234 <dd>
 235 <p>Like Test::More's is().  Checks if $got eq $expected.  This is the
 236 string version.</p>
 237 </dd>
 238 <dt><strong><a name="item_is_num"><strong>is_num</strong></a></strong>
 239
 240 <dd>
 241 <pre>
 242   $Test-&gt;is_num($got, $expected, $name);</pre>
 243 </dd>
 244 <dd>
 245 <p>Like Test::More's is().  Checks if $got == $expected.  This is the
 246 numeric version.</p>
 247 </dd>
 248 <dt><strong><a name="item_isnt_eq"><strong>isnt_eq</strong></a></strong>
 249
 250 <dd>
 251 <pre>
 252   $Test-&gt;isnt_eq($got, $dont_expect, $name);</pre>
 253 </dd>
 254 <dd>
 255 <p>Like Test::More's isnt().  Checks if $got ne $dont_expect.  This is
 256 the string version.</p>
 257 </dd>
 258 <dt><strong><a name="item_isnt_num"><strong>isnt_num</strong></a></strong>
 259
 260 <dd>
 261 <pre>
 262   $Test-&gt;is_num($got, $dont_expect, $name);</pre>
 263 </dd>
 264 <dd>
 265 <p>Like Test::More's isnt().  Checks if $got ne $dont_expect.  This is
 266 the numeric version.</p>
 267 </dd>
 268 <dt><strong><a name="item_like"><strong>like</strong></a></strong>
 269
 270 <dd>
 271 <pre>
 272   $Test-&gt;like($this, qr/$regex/, $name);
 273   $Test-&gt;like($this, '/$regex/', $name);</pre>
 274 </dd>
 275 <dd>
 276 <p>Like Test::More's like().  Checks if $this matches the given $regex.</p>
 277 </dd>
 278 <dd>
 279 <p>You'll want to avoid qr// if you want your tests to work before 5.005.</p>
 280 </dd>
 281 <dt><strong><a name="item_unlike"><strong>unlike</strong></a></strong>
 282
 283 <dd>
 284 <pre>
 285   $Test-&gt;unlike($this, qr/$regex/, $name);
 286   $Test-&gt;unlike($this, '/$regex/', $name);</pre>
 287 </dd>
 288 <dd>
 289 <p>Like Test::More's unlike().  Checks if $this <strong>does not match</strong> the
 290 given $regex.</p>
 291 </dd>
 292 <dt><strong><a name="item_maybe_regex"><strong>maybe_regex</strong></a></strong>
 293
 294 <dd>
 295 <pre>
 296   $Test-&gt;maybe_regex(qr/$regex/);
 297   $Test-&gt;maybe_regex('/$regex/');</pre>
 298 </dd>
 299 <dd>
 300 <p>Convenience method for building testing functions that take regular
 301 expressions as arguments, but need to work before perl 5.005.</p>
 302 </dd>
 303 <dd>
 304 <p>Takes a quoted regular expression produced by qr//, or a string
 305 representing a regular expression.</p>
 306 </dd>
 307 <dd>
 308 <p>Returns a Perl value which may be used instead of the corresponding
 309 regular expression, or undef if it's argument is not recognised.</p>
 310 </dd>
 311 <dd>
 312 <p>For example, a version of like(), sans the useful diagnostic messages,
 313 could be written as:</p>
 314 </dd>
 315 <dd>
 316 <pre>
 317   sub laconic_like {
 318       my ($self, $this, $regex, $name) = @_;
 319       my $usable_regex = $self-&gt;maybe_regex($regex);
 320       die &quot;expecting regex, found '$regex'\n&quot;
 321           unless $usable_regex;
 322       $self-&gt;ok($this =~ m/$usable_regex/, $name);
 323   }</pre>
 324 </dd>
 325 <dt><strong><a name="item_cmp_ok"><strong>cmp_ok</strong></a></strong>
 326
 327 <dd>
 328 <pre>
 329   $Test-&gt;cmp_ok($this, $type, $that, $name);</pre>
 330 </dd>
 331 <dd>
 332 <p>Works just like Test::More's cmp_ok().</p>
 333 </dd>
 334 <dd>
 335 <pre>
 336     $Test-&gt;cmp_ok($big_num, '!=', $other_big_num);</pre>
 337 </dd>
 338 <dt><strong><a name="item_bail_out"><strong>BAIL_OUT</strong></a></strong>
 339
 340 <dd>
 341 <pre>
 342     $Test-&gt;BAIL_OUT($reason);</pre>
 343 </dd>
 344 <dd>
 345 <p>Indicates to the Test::Harness that things are going so badly all
 346 testing should terminate.  This includes running any additional test
 347 scripts.</p>
 348 </dd>
 349 <dd>
 350 <p>It will exit with 255.</p>
 351 </dd>
 352 <dt><strong><a name="item_skip"><strong>skip</strong></a></strong>
 353
 354 <dd>
 355 <pre>
 356     $Test-&gt;skip;
 357     $Test-&gt;skip($why);</pre>
 358 </dd>
 359 <dd>
 360 <p>Skips the current test, reporting $why.</p>
 361 </dd>
 362 <dt><strong><a name="item_todo_skip"><strong>todo_skip</strong></a></strong>
 363
 364 <dd>
 365 <pre>
 366   $Test-&gt;todo_skip;
 367   $Test-&gt;todo_skip($why);</pre>
 368 </dd>
 369 <dd>
 370 <p>Like skip(), only it will declare the test as failing and TODO.  Similar
 371 to</p>
 372 </dd>
 373 <dd>
 374 <pre>
 375     print &quot;not ok $tnum # TODO $why\n&quot;;</pre>
 376 </dd>
 377 </dl>
 378 <p>
 379 </p>
 380 <h2><a name="test_style">Test style</a></h2>
 381 <dl>
 382 <dt><strong><a name="item_level"><strong>level</strong></a></strong>
 383
 384 <dd>
 385 <pre>
 386     $Test-&gt;level($how_high);</pre>
 387 </dd>
 388 <dd>
 389 <p>How far up the call stack should $Test look when reporting where the
 390 test failed.</p>
 391 </dd>
 392 <dd>
 393 <p>Defaults to 1.</p>
 394 </dd>
 395 <dd>
 396 <p>Setting $Test::Builder::Level overrides.  This is typically useful
 397 localized:</p>
 398 </dd>
 399 <dd>
 400 <pre>
 401     {
 402         local $Test::Builder::Level = 2;
 403         $Test-&gt;ok($test);
 404     }</pre>
 405 </dd>
 406 <dt><strong><a name="item_use_numbers"><strong>use_numbers</strong></a></strong>
 407
 408 <dd>
 409 <pre>
 410     $Test-&gt;use_numbers($on_or_off);</pre>
 411 </dd>
 412 <dd>
 413 <p>Whether or not the test should output numbers.  That is, this if true:</p>
 414 </dd>
 415 <dd>
 416 <pre>
 417   ok 1
 418   ok 2
 419   ok 3</pre>
 420 </dd>
 421 <dd>
 422 <p>or this if false</p>
 423 </dd>
 424 <dd>
 425 <pre>
 426   ok
 427   ok
 428   ok</pre>
 429 </dd>
 430 <dd>
 431 <p>Most useful when you can't depend on the test output order, such as
 432 when threads or forking is involved.</p>
 433 </dd>
 434 <dd>
 435 <p>Test::Harness will accept either, but avoid mixing the two styles.</p>
 436 </dd>
 437 <dd>
 438 <p>Defaults to on.</p>
 439 </dd>
 440 <dt><strong><a name="item_no_diag"><strong>no_diag</strong></a></strong>
 441
 442 <dd>
 443 <pre>
 444     $Test-&gt;no_diag($no_diag);</pre>
 445 </dd>
 446 <dd>
 447 <p>If set true no diagnostics will be printed.  This includes calls to
 448 diag().</p>
 449 </dd>
 450 <dt><strong><a name="item_no_ending"><strong>no_ending</strong></a></strong>
 451
 452 <dd>
 453 <pre>
 454     $Test-&gt;no_ending($no_ending);</pre>
 455 </dd>
 456 <dd>
 457 <p>Normally, Test::Builder does some extra diagnostics when the test
 458 ends.  It also changes the exit code as described below.</p>
 459 </dd>
 460 <dd>
 461 <p>If this is true, none of that will be done.</p>
 462 </dd>
 463 <dt><strong><a name="item_no_header"><strong>no_header</strong></a></strong>
 464
 465 <dd>
 466 <pre>
 467     $Test-&gt;no_header($no_header);</pre>
 468 </dd>
 469 <dd>
 470 <p>If set to true, no ``1..N'' header will be printed.</p>
 471 </dd>
 472 </dl>
 473 <p>
 474 </p>
 475 <h2><a name="output">Output</a></h2>
 476 <p>Controlling where the test output goes.</p>
 477 <p>It's ok for your test to change where STDOUT and STDERR point to,
 478 Test::Builder's default output settings will not be affected.</p>
 479 <dl>
 480 <dt><strong><a name="item_diag"><strong>diag</strong></a></strong>
 481
 482 <dd>
 483 <pre>
 484     $Test-&gt;diag(@msgs);</pre>
 485 </dd>
 486 <dd>
 487 <p>Prints out the given @msgs.  Like <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_print"><code>print</code></a>, arguments are simply
 488 appended together.</p>
 489 </dd>
 490 <dd>
 491 <p>Normally, it uses the <a href="#item_failure_output"><code>failure_output()</code></a> handle, but if this is for a
 492 TODO test, the <a href="#item_todo_output"><code>todo_output()</code></a> handle is used.</p>
 493 </dd>
 494 <dd>
 495 <p>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.</p>
 498 </dd>
 499 <dd>
 500 <p>We encourage using this rather than calling print directly.</p>
 501 </dd>
 502 <dd>
 503 <p>Returns false.  Why?  Because <a href="#item_diag"><code>diag()</code></a> is often used in conjunction with
 504 a failing test (<a href="#item_ok"><code>ok() || diag()</code></a>) it ``passes through'' the failure.</p>
 505 </dd>
 506 <dd>
 507 <pre>
 508     return ok(...) || diag(...);</pre>
 509 </dd>
 510 <dt><strong><a name="item__print_diag"><strong>_print_diag</strong></a></strong>
 511
 512 <dd>
 513 <pre>
 514     $Test-&gt;_print_diag(@msg);</pre>
 515 </dd>
 516 <dd>
 517 <p>Like _print, but prints to the current diagnostic filehandle.</p>
 518 </dd>
 519 <dt><strong><a name="item_output"><strong>output</strong></a></strong>
 520
 521 <dd>
 522 <pre>
 523     $Test-&gt;output($fh);
 524     $Test-&gt;output($file);</pre>
 525 </dd>
 526 <dd>
 527 <p>Where normal ``ok/not ok'' test output should go.</p>
 528 </dd>
 529 <dd>
 530 <p>Defaults to STDOUT.</p>
 531 </dd>
 532 <dt><strong><a name="item_failure_output"><strong>failure_output</strong></a></strong>
 533
 534 <dd>
 535 <pre>
 536     $Test-&gt;failure_output($fh);
 537     $Test-&gt;failure_output($file);</pre>
 538 </dd>
 539 <dd>
 540 <p>Where diagnostic output on test failures and <a href="#item_diag"><code>diag()</code></a> should go.</p>
 541 </dd>
 542 <dd>
 543 <p>Defaults to STDERR.</p>
 544 </dd>
 545 <dt><strong><a name="item_todo_output"><strong>todo_output</strong></a></strong>
 546
 547 <dd>
 548 <pre>
 549     $Test-&gt;todo_output($fh);
 550     $Test-&gt;todo_output($file);</pre>
 551 </dd>
 552 <dd>
 553 <p>Where diagnostics about todo test failures and <a href="#item_diag"><code>diag()</code></a> should go.</p>
 554 </dd>
 555 <dd>
 556 <p>Defaults to STDOUT.</p>
 557 </dd>
 558 </dl>
 559 <p>
 560 </p>
 561 <h2><a name="test_status_and_info">Test Status and Info</a></h2>
 562 <dl>
 563 <dt><strong><a name="item_current_test"><strong>current_test</strong></a></strong>
 564
 565 <dd>
 566 <pre>
 567     my $curr_test = $Test-&gt;current_test;
 568     $Test-&gt;current_test($num);</pre>
 569 </dd>
 570 <dd>
 571 <p>Gets/sets the current test number we're on.  You usually shouldn't
 572 have to set this.</p>
 573 </dd>
 574 <dd>
 575 <p>If set forward, the details of the missing tests are filled in as 'unknown'.
 576 if set backward, the details of the intervening tests are deleted.  You
 577 can erase history if you really want to.</p>
 578 </dd>
 579 <dt><strong><a name="item_summary"><strong>summary</strong></a></strong>
 580
 581 <dd>
 582 <pre>
 583     my @tests = $Test-&gt;summary;</pre>
 584 </dd>
 585 <dd>
 586 <p>A simple summary of the tests so far.  True for pass, false for fail.
 587 This is a logical pass/fail, so todos are passes.</p>
 588 </dd>
 589 <dd>
 590 <p>Of course, test #1 is $tests[0], etc...</p>
 591 </dd>
 592 <dt><strong><a name="item_details"><strong>details</strong></a></strong>
 593
 594 <dd>
 595 <pre>
 596     my @tests = $Test-&gt;details;</pre>
 597 </dd>
 598 <dd>
 599 <p>Like summary(), but with a lot more detail.</p>
 600 </dd>
 601 <dd>
 602 <pre>
 603     $tests[$test_num - 1] =
 604             { 'ok'       =&gt; is the test considered a pass?
 605               actual_ok  =&gt; did it literally say 'ok'?
 606               name       =&gt; name of the test (if any)
 607               type       =&gt; type of test (if any, see below).
 608               reason     =&gt; reason for the above (if any)
 609             };</pre>
 610 </dd>
 611 <dd>
 612 <p>'ok' is true if Test::Harness will consider the test to be a pass.</p>
 613 </dd>
 614 <dd>
 615 <p>'actual_ok' is a reflection of whether or not the test literally
 616 printed 'ok' or 'not ok'.  This is for examining the result of 'todo'
 617 tests.</p>
 618 </dd>
 619 <dd>
 620 <p>'name' is the name of the test.</p>
 621 </dd>
 622 <dd>
 623 <p>'type' indicates if it was a special test.  Normal tests have a type
 624 of ''.  Type can be one of the following:</p>
 625 </dd>
 626 <dd>
 627 <pre>
 628     skip        see skip()
 629     todo        see todo()
 630     todo_skip   see todo_skip()
 631     unknown     see below</pre>
 632 </dd>
 633 <dd>
 634 <p>Sometimes the Test::Builder test counter is incremented without it
 635 printing any test output, for example, when <a href="#item_current_test"><code>current_test()</code></a> is changed.
 636 In these cases, Test::Builder doesn't know the result of the test, so
 637 it's type is 'unkown'.  These details for these tests are filled in.
 638 They are considered ok, but the name and actual_ok is left undef.</p>
 639 </dd>
 640 <dd>
 641 <p>For example ``not ok 23 - hole count # TODO insufficient donuts'' would
 642 result in this structure:</p>
 643 </dd>
 644 <dd>
 645 <pre>
 646     $tests[22] =    # 23 - 1, since arrays start from 0.
 647       { ok        =&gt; 1,   # logically, the test passed since it's todo
 648         actual_ok =&gt; 0,   # in absolute terms, it failed
 649         name      =&gt; 'hole count',
 650         type      =&gt; 'todo',
 651         reason    =&gt; 'insufficient donuts'
 652       };</pre>
 653 </dd>
 654 <dt><strong><a name="item_todo"><strong>todo</strong></a></strong>
 655
 656 <dd>
 657 <pre>
 658     my $todo_reason = $Test-&gt;todo;
 659     my $todo_reason = $Test-&gt;todo($pack);</pre>
 660 </dd>
 661 <dd>
 662 <p><a href="#item_todo"><code>todo()</code></a> looks for a $TODO variable in your tests.  If set, all tests
 663 will be considered 'todo' (see Test::More and Test::Harness for
 664 details).  Returns the reason (ie. the value of $TODO) if running as
 665 todo tests, false otherwise.</p>
 666 </dd>
 667 <dd>
 668 <p><a href="#item_todo"><code>todo()</code></a> is about finding the right package to look for $TODO in.  It
 669 uses the <a href="#item_exported_to"><code>exported_to()</code></a> package to find it.  If that's not set, it's
 670 pretty good at guessing the right package to look at based on $Level.</p>
 671 </dd>
 672 <dd>
 673 <p>Sometimes there is some confusion about where <a href="#item_todo"><code>todo()</code></a> should be looking
 674 for the $TODO variable.  If you want to be sure, tell it explicitly
 675 what $pack to use.</p>
 676 </dd>
 677 <dt><strong><a name="item_caller"><strong>caller</strong></a></strong>
 678
 679 <dd>
 680 <pre>
 681     my $package = $Test-&gt;caller;
 682     my($pack, $file, $line) = $Test-&gt;caller;
 683     my($pack, $file, $line) = $Test-&gt;caller($height);</pre>
 684 </dd>
 685 <dd>
 686 <p>Like the normal caller(), except it reports according to your level().</p>
 687 </dd>
 688 </dl>
 689 <p>
 690 </p>
 691 <hr />
 692 <h1><a name="exit_codes">EXIT CODES</a></h1>
 693 <p>If all your tests passed, Test::Builder will exit with zero (which is
 694 normal).  If anything failed it will exit with how many failed.  If
 695 you run less (or more) tests than you planned, the missing (or extras)
 696 will be considered failures.  If no tests were ever run Test::Builder
 697 will throw a warning and exit with 255.  If the test died, even after
 698 having successfully completed all its tests, it will still be
 699 considered a failure and will exit with 255.</p>
 700 <p>So the exit codes are...</p>
 701 <pre>
 702     0                   all tests successful
 703     255                 test died or all passed but wrong # of tests run
 704     any other number    how many failed (including missing or extras)</pre>
 705 <p>If you fail more than 254 tests, it will be reported as 254.</p>
 706 <p>
 707 </p>
 708 <hr />
 709 <h1><a name="threads">THREADS</a></h1>
 710 <p>In perl 5.8.0 and later, Test::Builder is thread-safe.  The test
 711 number is shared amongst all threads.  This means if one thread sets
 712 the test number using <a href="#item_current_test"><code>current_test()</code></a> they will all be effected.</p>
 713 <p>Test::Builder is only thread-aware if threads.pm is loaded <em>before</em>
 714 Test::Builder.</p>
 715 <p>
 716 </p>
 717 <hr />
 718 <h1><a name="examples">EXAMPLES</a></h1>
 719 <p>CPAN can provide the best examples.  Test::Simple, Test::More,
 720 Test::Exception and Test::Differences all use Test::Builder.</p>
 721 <p>
 722 </p>
 723 <hr />
 724 <h1><a name="see_also">SEE ALSO</a></h1>
 725 <p>Test::Simple, Test::More, Test::Harness</p>
 726 <p>
 727 </p>
 728 <hr />
 729 <h1><a name="authors">AUTHORS</a></h1>
 730 <p>Original code by chromatic, maintained by Michael G Schwern
 731 &lt;<a href="mailto:schwern@pobox.com">schwern@pobox.com</a>&gt;</p>
 732 <p>
 733 </p>
 734 <hr />
 735 <h1><a name="copyright">COPYRIGHT</a></h1>
 736 <p>Copyright 2002, 2004 by chromatic &lt;<a href="mailto:chromatic@wgz.org">chromatic@wgz.org</a>&gt; and
 737                         Michael G Schwern &lt;<a href="mailto:schwern@pobox.com">schwern@pobox.com</a>&gt;.</p>
 738 <p>This program is free software; you can redistribute it and/or
 739 modify it under the same terms as Perl itself.</p>
 740 <p>See <em><a href="http://www.perl.com/perl/misc/Artistic.html">http://www.perl.com/perl/misc/Artistic.html</a></em></p>
 741 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 742 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 743 <big><strong><span class="block">&nbsp;Test::Builder - Backend for building test libraries</span></strong></big>
 744 </td></tr>
 745 </table>
 746
 747 </body>
 748
 749 </html>