.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test2::Manual::Tooling::TestBuilder 3pm"
.TH Test2::Manual::Tooling::TestBuilder 3pm "2019-05-06" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test2::Manual::Tooling::TestBuilder \- This section maps Test::Builder methods
to Test2 concepts.
.SH "DESCRIPTION"
.IX Header "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.
.SH "CONTEXT"
.IX Header "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:
.PP
.Vb 1
\&    use Test2::API qw/context/;
\&
\&    sub my_tool {
\&        my $ctx  = context();
\&
\&        ... do work ...
\&
\&        $ctx\->ok(1, "a passing assertion");
\&
\&        $ctx\->release;
\&
\&        return $whatever;
\&    }
.Ve
.PP
The original Test::Builder style was this:
.PP
.Vb 2
\&    use Test::Builder;
\&    my $tb = Test::Builder\->new; # gets the singleton
\&
\&    sub my_tool {
\&        ... do work ...
\&
\&        $tb\->ok(1, "a passing assertion");
\&
\&        return $whatever;
\&    }
.Ve
.SH "TEST BUILDER METHODS"
.IX Header "TEST BUILDER METHODS"
.ie n .IP "$tb\->\s-1BAIL_OUT\s0($reason)" 4
.el .IP "\f(CW$tb\fR\->\s-1BAIL_OUT\s0($reason)" 4
.IX Item "$tb->BAIL_OUT($reason)"
The context object has a 'bail' method:
.Sp
.Vb 1
\&    $ctx\->bail($reason)
.Ve
.ie n .IP "$tb\->diag($string)" 4
.el .IP "\f(CW$tb\fR\->diag($string)" 4
.IX Item "$tb->diag($string)"
.PD 0
.ie n .IP "$tb\->note($string)" 4
.el .IP "\f(CW$tb\fR\->note($string)" 4
.IX Item "$tb->note($string)"
.PD
The context object has diag and note methods:
.Sp
.Vb 2
\&    $ctx\->diag($string);
\&    $ctx\->note($string);
.Ve
.ie n .IP "$tb\->done_testing" 4
.el .IP "\f(CW$tb\fR\->done_testing" 4
.IX Item "$tb->done_testing"
The context object has a done_testing method:
.Sp
.Vb 1
\&    $ctx\->done_testing;
.Ve
.Sp
Unlike the Test::Builder version, no arguments are allowed.
.ie n .IP "$tb\->like" 4
.el .IP "\f(CW$tb\fR\->like" 4
.IX Item "$tb->like"
.PD 0
.ie n .IP "$tb\->unlike" 4
.el .IP "\f(CW$tb\fR\->unlike" 4
.IX Item "$tb->unlike"
.PD
These are not part of context, instead look at Test2::Compare and
Test2::Tools::Compare.
.ie n .IP "$tb\->ok($bool, $name)" 4
.el .IP "\f(CW$tb\fR\->ok($bool, \f(CW$name\fR)" 4
.IX Item "$tb->ok($bool, $name)"
.Vb 3
\&    # Preferred
\&    $ctx\->pass($name);
\&    $ctx\->fail($name, @diag);
\&
\&    # Discouraged, but supported:
\&    $ctx\->ok($bool, $name, \e@failure_diags)
.Ve
.ie n .IP "$tb\->subtest" 4
.el .IP "\f(CW$tb\fR\->subtest" 4
.IX Item "$tb->subtest"
use the \f(CW\*(C`Test2::API::run_subtest()\*(C'\fR function instead. See Test2::API for documentation.
.ie n .IP "$tb\->todo_start" 4
.el .IP "\f(CW$tb\fR\->todo_start" 4
.IX Item "$tb->todo_start"
.PD 0
.ie n .IP "$tb\->todo_end" 4
.el .IP "\f(CW$tb\fR\->todo_end" 4
.IX Item "$tb->todo_end"
.PD
See Test2::Tools::Todo instead.
.ie n .IP "$tb\->output, $tb\->failure_output, and $tb\->todo_output" 4
.el .IP "\f(CW$tb\fR\->output, \f(CW$tb\fR\->failure_output, and \f(CW$tb\fR\->todo_output" 4
.IX Item "$tb->output, $tb->failure_output, and $tb->todo_output"
These are handled via formatters now. See Test2::Formatter and
Test2::Formatter::TAP.
.SH "LEVEL"
.IX Header "LEVEL"
Test::Builder had the \f(CW$Test::Builder::Level\fR 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.
.PP
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.
.PP
Test2 is also smart enough to honor c<$Test::Builder::Level> if it is set.
.SH "TODO"
.IX Header "TODO"
Test::Builder used the \f(CW$TODO\fR package variable to set the \s-1TODO\s0 state. This
was confusing, and easy to get wrong. See Test2::Tools::Todo for the modern
way to accomplish a \s-1TODO\s0 state.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Manual can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR