CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • Construction
  • Setting up tests
  • Running tests
  • Other Testing Methods
  • Test building utility methods
  • Test style
  • Output
  • Test Status and Info
• EXIT CODES
• THREADS
• MEMORY
• EXAMPLES
• SEE ALSO
• AUTHORS
• COPYRIGHT

#NAME

Test::Builder - Backend for building test libraries

#SYNOPSIS

package My::Test::Module;
use base 'Test::Builder::Module';

my $CLASS = __PACKAGE__;

sub ok {
    my($test, $name) = @_;
    my $tb = $CLASS->builder;

    $tb->ok($test, $name);
}

#DESCRIPTION

Test::Simple and Test::More have proven to be popular testing modules, but they're not always flexible enough. Test::Builder provides a building block upon which to write your own test libraries which can work together.

#Construction

#new

my $Test = Test::Builder->new;

Returns a Test::Builder object representing the current state of the test.

Since you only run one test per program new always returns the same Test::Builder object. No matter how many times you call new(), you're getting the same object. This is called a singleton. This is done so that multiple modules share such global information as the test counter and where test output is going.

If you want a completely new Test::Builder object different from the singleton, use create.

#create

my $Test = Test::Builder->create;

Ok, so there can be more than one Test::Builder object and this is how you get it. You might use this instead of new() if you're testing a Test::Builder based module, but otherwise you probably want new.

NOTE: the implementation is not complete. level, for example, is still shared amongst all Test::Builder objects, even ones created using this method. Also, the method name may change in the future.

#child

my $child = $builder->child($name_of_child);
$child->plan( tests => 4 );
$child->ok(some_code());
...
$child->finalize;

Returns a new instance of Test::Builder. Any output from this child will be indented four spaces more than the parent's indentation. When done, the finalize method must be called explicitly.

Trying to create a new child with a previous child still active (i.e., finalize not called) will croak.

Trying to run a test when you have an open child will also croak and cause the test suite to fail.

#subtest

$builder->subtest($name, \&subtests);

See documentation of subtest in Test::More.

#finalize

my $ok = $child->finalize;

When your child is done running tests, you must call finalize to clean up and tell the parent your pass/fail status.

Calling finalize on a child with open children will croak.

If the child falls out of scope before finalize is called, a failure diagnostic will be issued and the child is considered to have failed.

No attempt to call methods on a child after finalize is called is guaranteed to succeed.

Calling this on the root builder is a no-op.

#parent

if ( my $parent = $builder->parent ) {
    ...
}

Returns the parent Test::Builder instance, if any. Only used with child builders for nested TAP.

#name

diag $builder->name;

Returns the name of the current builder. Top level builders default to $0 (the name of the executable). Child builders are named via the child method. If no name is supplied, will be named "Child of $parent->name".

#reset

$Test->reset;

Reinitializes the Test::Builder singleton to its original state. Mostly useful for tests run in persistent environments where the same test might be run multiple times in the same process.

#