Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Manual::Tooling::TestBuilder.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Tooling::TestBuilder 3pm"
61 .TH Test2::Manual::Tooling::TestBuilder 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Tooling::TestBuilder \- This section maps Test::Builder methods
68 to Test2 concepts.
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 With Test::Builder tools were encouraged to use methods on the Test::Builder
72 singleton object. Test2 has a different approach, every tool should get a new
73 Test2::API::Context object, and call methods on that. This document maps
74 several concepts from Test::Builder to Test2.
75 .SH CONTEXT
76 .IX Header "CONTEXT"
77 First thing to do, stop using the Test::Builder singleton, in fact stop using
78 or even loading Test::Builder. Instead of Test::Builder each tool you write
79 should follow this template:
80 .PP
81 .Vb 1
82 \& use Test2::API qw/context/;
83 \&
84 \& sub my_tool {
85 \& my $ctx = context();
86 \&
87 \& ... do work ...
88 \&
89 \& $ctx\->ok(1, "a passing assertion");
90 \&
91 \& $ctx\->release;
92 \&
93 \& return $whatever;
94 \& }
95 .Ve
96 .PP
97 The original Test::Builder style was this:
98 .PP
99 .Vb 2
100 \& use Test::Builder;
101 \& my $tb = Test::Builder\->new; # gets the singleton
102 \&
103 \& sub my_tool {
104 \& ... do work ...
105 \&
106 \& $tb\->ok(1, "a passing assertion");
107 \&
108 \& return $whatever;
109 \& }
110 .Ve
111 .SH "TEST BUILDER METHODS"
112 .IX Header "TEST BUILDER METHODS"
113 .ie n .IP $tb\->BAIL_OUT($reason) 4
114 .el .IP \f(CW$tb\fR\->BAIL_OUT($reason) 4
115 .IX Item "$tb->BAIL_OUT($reason)"
116 The context object has a \*(Aqbail\*(Aq method:
117 .Sp
118 .Vb 1
119 \& $ctx\->bail($reason)
120 .Ve
121 .ie n .IP $tb\->diag($string) 4
122 .el .IP \f(CW$tb\fR\->diag($string) 4
123 .IX Item "$tb->diag($string)"
124 .PD 0
125 .ie n .IP $tb\->note($string) 4
126 .el .IP \f(CW$tb\fR\->note($string) 4
127 .IX Item "$tb->note($string)"
128 .PD
129 The context object has diag and note methods:
130 .Sp
131 .Vb 2
132 \& $ctx\->diag($string);
133 \& $ctx\->note($string);
134 .Ve
135 .ie n .IP $tb\->done_testing 4
136 .el .IP \f(CW$tb\fR\->done_testing 4
137 .IX Item "$tb->done_testing"
138 The context object has a done_testing method:
139 .Sp
140 .Vb 1
141 \& $ctx\->done_testing;
142 .Ve
143 .Sp
144 Unlike the Test::Builder version, no arguments are allowed.
145 .ie n .IP $tb\->like 4
146 .el .IP \f(CW$tb\fR\->like 4
147 .IX Item "$tb->like"
148 .PD 0
149 .ie n .IP $tb\->unlike 4
150 .el .IP \f(CW$tb\fR\->unlike 4
151 .IX Item "$tb->unlike"
152 .PD
153 These are not part of context, instead look at Test2::Compare and
154 Test2::Tools::Compare.
155 .ie n .IP "$tb\->ok($bool, $name)" 4
156 .el .IP "\f(CW$tb\fR\->ok($bool, \f(CW$name\fR)" 4
157 .IX Item "$tb->ok($bool, $name)"
158 .Vb 3
159 \& # Preferred
160 \& $ctx\->pass($name);
161 \& $ctx\->fail($name, @diag);
162 \&
163 \& # Discouraged, but supported:
164 \& $ctx\->ok($bool, $name, \e@failure_diags)
165 .Ve
166 .ie n .IP $tb\->subtest 4
167 .el .IP \f(CW$tb\fR\->subtest 4
168 .IX Item "$tb->subtest"
169 use the \f(CWTest2::API::run_subtest()\fR function instead. See Test2::API for documentation.
170 .ie n .IP $tb\->todo_start 4
171 .el .IP \f(CW$tb\fR\->todo_start 4
172 .IX Item "$tb->todo_start"
173 .PD 0
174 .ie n .IP $tb\->todo_end 4
175 .el .IP \f(CW$tb\fR\->todo_end 4
176 .IX Item "$tb->todo_end"
177 .PD
178 See Test2::Tools::Todo instead.
179 .ie n .IP "$tb\->output, $tb\->failure_output, and $tb\->todo_output" 4
180 .el .IP "\f(CW$tb\fR\->output, \f(CW$tb\fR\->failure_output, and \f(CW$tb\fR\->todo_output" 4
181 .IX Item "$tb->output, $tb->failure_output, and $tb->todo_output"
182 These are handled via formatters now. See Test2::Formatter and
183 Test2::Formatter::TAP.
184 .SH LEVEL
185 .IX Header "LEVEL"
186 Test::Builder had the \f(CW$Test::Builder::Level\fR variable that you could
187 modify in order to set the stack depth. This was useful if you needed to nest
188 tools and wanted to make sure your file and line number were correct. It was
189 also frustrating and prone to errors. Some people never even discovered the
190 level variable and always had incorrect line numbers when their tools would
191 fail.
192 .PP
193 Test2 uses the context system, which solves the problem a better way. The
194 top\-most tool get a context, and holds on to it until it is done. Any tool
195 nested under the first will find and use the original context instead of
196 generating a new one. This means the level problem is solved for free, no
197 variables to mess with.
198 .PP
199 Test2 is also smart enough to honor \f(CW$Test::Builder::Level\fR if it is set.
200 .SH TODO
201 .IX Header "TODO"
202 Test::Builder used the \f(CW$TODO\fR package variable to set the TODO state. This
203 was confusing, and easy to get wrong. See Test2::Tools::Todo for the modern
204 way to accomplish a TODO state.
205 .SH "SEE ALSO"
206 .IX Header "SEE ALSO"
207 Test2::Manual \- Primary index of the manual.
208 .SH SOURCE
209 .IX Header "SOURCE"
210 The source code repository for Test2\-Manual can be found at
211 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
212 .SH MAINTAINERS
213 .IX Header "MAINTAINERS"
214 .IP "Chad Granum <[email protected]>" 4
215 .IX Item "Chad Granum <[email protected]>"
216 .SH AUTHORS
217 .IX Header "AUTHORS"
218 .IP "Chad Granum <[email protected]>" 4
219 .IX Item "Chad Granum <[email protected]>"
220 .SH COPYRIGHT
221 .IX Header "COPYRIGHT"
222 Copyright Chad Granum <[email protected]>.
223 .PP
224 This program is free software; you can redistribute it and/or
225 modify it under the same terms as Perl itself.
226 .PP
227 See \fIhttp://dev.perl.org/licenses/\fR