Test2:...Builder(3perl) Perl Programmers Reference GuideTest2:...Builder(3perl)
NAME
Test2::Manual::Tooling::TestBuilder - This section maps Test::Builder
methods to Test2 concepts.
DESCRIPTION
With Test::Builder tools were encouraged to use methods on the
Test::Builder singleton object. Test2 has a different approach, every
tool should get a new Test2::API::Context object, and call methods on
that. This document maps several concepts from Test::Builder to Test2.
CONTEXT
First thing to do, stop using the Test::Builder singleton, in fact stop
using or even loading Test::Builder. Instead of Test::Builder each tool
you write should follow this template:
use Test2::API qw/context/;
sub my_tool {
my $ctx = context();
... do work ...
$ctx->ok(1, "a passing assertion");
$ctx->release;
return $whatever;
}
The original Test::Builder style was this:
use Test::Builder;
my $tb = Test::Builder->new; # gets the singleton
sub my_tool {
... do work ...
$tb->ok(1, "a passing assertion");
return $whatever;
}
TEST BUILDER METHODS
$tb->BAIL_OUT($reason)
The context object has a 'bail' method:
$ctx->bail($reason)
$tb->diag($string)
$tb->note($string)
The context object has diag and note methods:
$ctx->diag($string);
$ctx->note($string);
$tb->done_testing
The context object has a done_testing method:
$ctx->done_testing;
Unlike the Test::Builder version, no arguments are allowed.
$tb->like
$tb->unlike
These are not part of context, instead look at Test2::Compare and
Test2::Tools::Compare.
$tb->ok($bool, $name)
# Preferred
$ctx->pass($name);
$ctx->fail($name, @diag);
# Discouraged, but supported:
$ctx->ok($bool, $name, \@failure_diags)
$tb->subtest
use the Test2::API::run_subtest() function instead. See Test2::API
for documentation.
$tb->todo_start
$tb->todo_end
See Test2::Tools::Todo instead.
$tb->output, $tb->failure_output, and $tb->todo_output
These are handled via formatters now. See Test2::Formatter and
Test2::Formatter::TAP.
LEVEL
Test::Builder had the $Test::Builder::Level variable that you could
modify in order to set the stack depth. This was useful if you needed to
nest tools and wanted to make sure your file and line number were
correct. It was also frustrating and prone to errors. Some people never
even discovered the level variable and always had incorrect line numbers
when their tools would fail.
Test2 uses the context system, which solves the problem a better way.
The top-most tool get a context, and holds on to it until it is done.
Any tool nested under the first will find and use the original context
instead of generating a new one. This means the level problem is solved
for free, no variables to mess with.
Test2 is also smart enough to honor $Test::Builder::Level if it is set.
TODO
Test::Builder used the $TODO package variable to set the TODO state.
This was confusing, and easy to get wrong. See Test2::Tools::Todo for
the modern way to accomplish a TODO state.
SEE ALSO
Test2::Manual - Primary index of the manual.
SOURCE
The source code repository for Test2-Manual can be found at
https://github.com/Test-More/Test2-Suite/.
MAINTAINERS
Chad Granum <exodist@cpan.org>
AUTHORS
Chad Granum <exodist@cpan.org>
COPYRIGHT
Copyright 2018 Chad Granum <exodist@cpan.org>.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See http://dev.perl.org/licenses/
perl v5.40.1 2026-08-30 Test2:...Builder(3perl)
Generated by dwww version 1.16 on Sat Oct 3 06:00:54 CEST 2026.