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.36.0                                       2023-10-26              Test2::Manual:...ng::TestBuilder(3pm)