• NAME
• DESCRIPTION
• CONTEXT
• TEST BUILDER METHODS
• LEVEL
• TODO
• SEE ALSO
• SOURCE
• MAINTAINERS
• AUTHORS
• COPYRIGHT

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 the Test2::API::Context manpage 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 the Test2::Compare manpage and the Test2::Tools::Compare manpage.

$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 the Test2::API manpage for documentation.

$tb->todo_start

$tb->todo_end

See the Test2::Tools::Todo manpage instead.

$tb->output, $tb->failure_output, and $tb->todo_output

These are handled via formatters now. See the Test2::Formatter manpage and the Test2::Formatter::TAP manpage.

LEVEL

the Test::Builder manpage 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.

TODO

the Test::Builder manpage used the $TODO package variable to set the TODO state. This was confusing, and easy to get wrong. See the Test2::Tools::Todo manpage for the modern way to accomplish a TODO state.

SEE ALSO

the Test2::Manual manpage - 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

AUTHORS

Chad Granum <exodist@cpan.org>Chad Granum

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/