<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Manual/Tooling/TestBuilder.md. Do not edit. -->

```{index} single: Test2::Manual::Tooling::TestBuilder
```

# 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](../../API/Context.md) 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:

```perl
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:

```perl
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:

    ```perl
    $ctx->bail($reason)
    ```

- $tb->diag($string)
- $tb->note($string)

    The context object has diag and note methods:

    ```perl
    $ctx->diag($string);
    $ctx->note($string);
    ```

- $tb->done\_testing

    The context object has a done\_testing method:

    ```perl
    $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](../../Compare.md) and
    [Test2::Tools::Compare](../../Tools/Compare.md).

- $tb->ok($bool, $name)

    ```perl
    # 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](../../API.md) for documentation.

- $tb->todo\_start
- $tb->todo\_end

    See ["skip($why)" in Test2::Tools::Basic](../../Tools/Basic.md), and [Test2::Todo](../../Todo.md) instead.

- $tb->output, $tb->failure\_output, and $tb->todo\_output

    These are handled via formatters now. See [Test2::Formatter](../../Formatter.md) and
    [Test2::Formatter::TAP](../../Formatter/TAP.md).

## LEVEL

[Test::Builder](../../../Test/Builder.md) 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](../../../Test2.md) 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](../../../Test2.md) is also smart enough to honor `$Test::Builder::Level` if it is set.

## TODO

[Test::Builder](../../../Test/Builder.md) used the `$TODO` package variable to set the TODO state. This
was confusing, and easy to get wrong. See [Test2::Tools::Todo](https://metacpan.org/pod/Test2::Tools::Todo) for the modern
way to accomplish a TODO state.

## SEE ALSO

[Test2::Manual](../../Manual.md) - 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/`