1Test2::Manual::Tooling:U:sTeerstCBounitlrdiebru(t3e)d PeTrelstD2o:c:uMmaennutaalt:i:oTnooling::TestBuilder(3)
2
3
4

NAME

6       Test2::Manual::Tooling::TestBuilder - This section maps Test::Builder
7       methods to Test2 concepts.
8

DESCRIPTION

10       With Test::Builder tools were encouraged to use methods on the
11       Test::Builder singleton object. Test2 has a different approach, every
12       tool should get a new Test2::API::Context object, and call methods on
13       that. This document maps several concepts from Test::Builder to Test2.
14

CONTEXT

16       First thing to do, stop using the Test::Builder singleton, in fact stop
17       using or even loading Test::Builder. Instead of Test::Builder each tool
18       you write should follow this template:
19
20           use Test2::API qw/context/;
21
22           sub my_tool {
23               my $ctx  = context();
24
25               ... do work ...
26
27               $ctx->ok(1, "a passing assertion");
28
29               $ctx->release;
30
31               return $whatever;
32           }
33
34       The original Test::Builder style was this:
35
36           use Test::Builder;
37           my $tb = Test::Builder->new; # gets the singleton
38
39           sub my_tool {
40               ... do work ...
41
42               $tb->ok(1, "a passing assertion");
43
44               return $whatever;
45           }
46

TEST BUILDER METHODS

48       $tb->BAIL_OUT($reason)
49           The context object has a 'bail' method:
50
51               $ctx->bail($reason)
52
53       $tb->diag($string)
54       $tb->note($string)
55           The context object has diag and note methods:
56
57               $ctx->diag($string);
58               $ctx->note($string);
59
60       $tb->done_testing
61           The context object has a done_testing method:
62
63               $ctx->done_testing;
64
65           Unlike the Test::Builder version, no arguments are allowed.
66
67       $tb->like
68       $tb->unlike
69           These are not part of context, instead look at Test2::Compare and
70           Test2::Tools::Compare.
71
72       $tb->ok($bool, $name)
73               # Preferred
74               $ctx->pass($name);
75               $ctx->fail($name, @diag);
76
77               # Discouraged, but supported:
78               $ctx->ok($bool, $name, \@failure_diags)
79
80       $tb->subtest
81           use the Test2::API::run_subtest() function instead. See Test2::API
82           for documentation.
83
84       $tb->todo_start
85       $tb->todo_end
86           See Test2::Tools::Todo instead.
87
88       $tb->output, $tb->failure_output, and $tb->todo_output
89           These are handled via formatters now. See Test2::Formatter and
90           Test2::Formatter::TAP.
91

LEVEL

93       Test::Builder had the $Test::Builder::Level variable that you could
94       modify in order to set the stack depth. This was useful if you needed
95       to nest tools and wanted to make sure your file and line number were
96       correct. It was also frustrating and prone to errors. Some people never
97       even discovered the level variable and always had incorrect line
98       numbers when their tools would fail.
99
100       Test2 uses the context system, which solves the problem a better way.
101       The top-most tool get a context, and holds on to it until it is done.
102       Any tool nested under the first will find and use the original context
103       instead of generating a new one. This means the level problem is solved
104       for free, no variables to mess with.
105
106       Test2 is also smart enough to honor c<$Test::Builder::Level> if it is
107       set.
108

TODO

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

SEE ALSO

115       Test2::Manual - Primary index of the manual.
116

SOURCE

118       The source code repository for Test2-Manual can be found at
119       https://github.com/Test-More/Test2-Suite/.
120

MAINTAINERS

122       Chad Granum <exodist@cpan.org>
123

AUTHORS

125       Chad Granum <exodist@cpan.org>
126

128       Copyright 2018 Chad Granum <exodist@cpan.org>.
129
130       This program is free software; you can redistribute it and/or modify it
131       under the same terms as Perl itself.
132
133       See http://dev.perl.org/licenses/
134
135
136
137perl v5.38.0                      2023-07T-e2s1t2::Manual::Tooling::TestBuilder(3)
Impressum