Rand Stats



Actions Status


Test::Builder - flexible framework for building TAP test libraries


my $tb = Test::Builder.new;


$tb.ok(1, 'This is a test');
$tb.ok(1, 'This is another test');



Test::Builder is meant to serve as a generic backend for test libraries. Put differently, it provides the basic "building blocks" and generic functionality needed for building your own application-specific TAP test libraries.

Test::Builder conforms to the Test Anything Protocol (TAP) specification.


Object Initialization


Returns the Test::Builder singleton object.

The new() method only returns a new object the first time that it's called. If called again, it simply returns the same object. This allows multiple modules to share the global information about the TAP harness's state.

Alternatively, if a singleton object is too limiting, you can use the create() method instead.


Returns a new Test::Builder instance.

The create() method should only be used under certain circumstances. For instance, when testing Test::Builder-based modules. In all other cases, it is recommended that you stick to using new() instead.

Implementing Tests

The following methods are responsible for performing the actual tests.

All methods take an optional string argument describing the nature of the test.

plan(Int $tests)

Declares how many tests are going to be run.

If called as .plan(*), then a plan will not be set. However, it is your job to call done() when all tests have been run.

ok(Mu $test, Str $description)

Evaluates $test in a boolean context. The test will pass if the expression evaluates to Bool::True and fail otherwise.

nok(Mu $test, Str $description)

The antithesis of ok(). Evaluates $test in a boolean context. The test will pass if the expression evaluates to Bool::False and fail otherwise.

Modifying Test Behavior

todo(Str $reason, Int $count)

Marks the next $count tests as failures but ignores the fact. Test execution will continue after displaying the message in $reason.

It's important to note that even though the tests are marked as failures, they will still be evaluated. If a test marked with todo() in fact passes, a warning message will be displayed.

TODO The todo() method doesn't actually does this yet but I want it to




Kevin Polulak


Test::Builder was largely inspired by chromatic's work on the old Test::Builder module for Pugs.

Additionally, Test::Builder is based on the Perl module of the same name also written by chromatic and Michael G. Schwern.


Copyright 2011 Kevin Polulak

Copyright 2012 - 2022 Raku Community

This program is distributed under the terms of the Artistic License 2.0.