Provided by: libtest2-suite-perl_0.000125-1_all bug


       Test2::Manual::Tooling::TestBuilder - This section maps Test::Builder methods to Test2


       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.


       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

           use Test2::API qw/context/;

           sub my_tool {
               my $ctx  = context();

               ... do work ...

               $ctx->ok(1, "a passing assertion");


               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;


           The context object has a 'bail' method:


           The context object has diag and note methods:


           The context object has a done_testing method:


           Unlike the Test::Builder version, no arguments are allowed.

           These are not part of context, instead look at Test2::Compare and

       $tb->ok($bool, $name)
               # Preferred
               $ctx->fail($name, @diag);

               # Discouraged, but supported:
               $ctx->ok($bool, $name, \@failure_diags)

           use the "Test2::API::run_subtest()" function instead. See Test2::API for

           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.


       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 c<$Test::Builder::Level> if it is set.


       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


       Test2::Manual - Primary index of the manual.


       The source code repository for Test2-Manual can be found at


       Chad Granum <>


       Chad Granum <>


       Copyright 2018 Chad Granum <>.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.