Test2::...tBuilder(3)

💖 NAME 💖

okay bestie, welcome to the Test2::Manual::Tooling::TestBuilder page — Test2::...tBuilder(3), straight outta the User Contributed Perl Documentation. The NAME tea: this section maps Test::Builder methods to Test2 concepts. 💅

✨ DESCRIPTION ✨

So back in Test::Builder land, tools were encouraged to call methods on the Test::Builder singleton object. Test2 is different, bestie: 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: stop using the Test::Builder singleton — fr fr, stop using it and even stop loading Test::Builder. Instead of Test::Builder, every 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) and $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 and $tb->unlike — these are not part of context, instead look at Test2::Compare and Test2::Tools::Compare.
• $tb->ok($bool, $name) — use this pattern:

# 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 and $tb->todo_end — see "skip($why)" in Test2::Tools::Basic, and Test2::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 gets 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. That 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/test-more/. 🔥

👑 MAINTAINERS 👑

• Chad Granum <exodist@cpan.org>

🌸 AUTHORS 🌸

• Chad Granum <exodist@cpan.org>

🧚 COPYRIGHT 🧚

Copyright 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/

---

okay that’s the whole page, bestie — brought to you by perl v5.42.0, dated 2025-07-28, and filed under Test2::...tBuilder(3). mwah 💖✨