local-lib5/man/man3/Test::Builder.3pm

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