Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Transition.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::Transition 3pm"
61 .TH Test2::Transition 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::Transition \- Transition notes when upgrading to Test2
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This is where gotchas and breakages related to the Test2 upgrade are
71 documented. The upgrade causes Test::Builder to defer to Test2 under the hood.
72 This transition is mostly transparent, but there are a few cases that can trip
73 you up.
74 .SH "THINGS THAT BREAK"
75 .IX Header "THINGS THAT BREAK"
76 This is the list of scenarios that break with the new internals.
77 .SS "Test::Builder1.5/2 conditionals"
78 .IX Subsection "Test::Builder1.5/2 conditionals"
79 \fIThe Problem\fR
80 .IX Subsection "The Problem"
81 .PP
82 a few years back there were two attempts to upgrade/replace Test::Builder.
83 Confusingly these were called Test::Builder2 and Test::Builder1.5, in that
84 order. Many people put conditionals in their code to check the Test::Builder
85 version number and adapt their code accordingly.
86 .PP
87 The Test::Builder2/1.5 projects both died out. Now the conditional code people
88 added has become a mine field. A vast majority of modules broken by Test2 fall
89 into this category.
90 .PP
91 \fIThe Fix\fR
92 .IX Subsection "The Fix"
93 .PP
94 The fix is to remove all Test::Builder1.5/2 related code. Either use the
95 legacy Test::Builder API, or use Test2 directly.
96 .SS "Replacing the Test::Builder singleton"
97 .IX Subsection "Replacing the Test::Builder singleton"
98 \fIThe Problem\fR
99 .IX Subsection "The Problem"
100 .PP
101 Some test modules would replace the Test::Builder singleton instance with their
102 own instance or subclass. This was usually done to intercept or modify results
103 as they happened.
104 .PP
105 The Test::Builder singleton is now a simple compatibility wrapper around
106 Test2. The Test::Builder singleton is no longer the central place for
107 results. Many results bypass the Test::Builder singleton completely, which
108 breaks and behavior intended when replacing the singleton.
109 .PP
110 \fIThe Fix\fR
111 .IX Subsection "The Fix"
112 .PP
113 If you simply want to intercept all results instead of letting them go to TAP,
114 you should look at the Test2::API docs and read about pushing a new hub onto
115 the hub stack. Replacing the hub temporarily is now the correct way to
116 intercept results.
117 .PP
118 If your goal is purely monitoring of events use the \f(CW\*(C`Test2::Hub\->listen()\*(C'\fR
119 method exported by Test::More to watch events as they are fired. If you wish to
120 modify results before they go to TAP look at the \f(CW\*(C`Test2::Hub\->filter()\*(C'\fR
121 method.
122 .SS "Directly Accessing Hash Elements"
123 .IX Subsection "Directly Accessing Hash Elements"
124 \fIThe Problem\fR
125 .IX Subsection "The Problem"
126 .PP
127 Some modules look directly at hash keys on the Test::Builder singleton. The
128 problem here is that the Test::Builder singleton no longer holds anything
129 important.
130 .PP
131 \fIThe Fix\fR
132 .IX Subsection "The Fix"
133 .PP
134 The fix is to use the API specified in Test2::API to look at or modify state
135 as needed.
136 .SS "Subtest indentation"
137 .IX Subsection "Subtest indentation"
138 \fIThe Problem\fR
139 .IX Subsection "The Problem"
140 .PP
141 An early change, in fact the change that made Test2 an idea, was a change to
142 the indentation of the subtest note. It was decided it would be more readable
143 to outdent the subtest note instead of having it inline with the subtest:
144 .PP
145 .Vb 4
146 \& # subtest foo
147 \& ok 1 \- blah
148 \& 1..1
149 \& ok 1 \- subtest foo
150 .Ve
151 .PP
152 The old style indented the note:
153 .PP
154 .Vb 4
155 \& # subtest foo
156 \& ok 1 \- blah
157 \& 1..1
158 \& ok 1 \- subtest foo
159 .Ve
160 .PP
161 This breaks tests that do string comparison of TAP output.
162 .PP
163 \fIThe Fix\fR
164 .IX Subsection "The Fix"
165 .PP
166 .Vb 1
167 \& my $indent = $INC{\*(AqTest2/API.pm\*(Aq} ? \*(Aq\*(Aq : \*(Aq \*(Aq;
168 \&
169 \& is(
170 \& $subtest_output,
171 \& "${indent}# subtest foo",
172 \& "Got subtest note"
173 \& );
174 .Ve
175 .PP
176 Check if \f(CW$INC{\*(AqTest2/API.pm\*(Aq}\fR is set, if it is then no indentation should be
177 expected. If it is not set, then the old Test::Builder is in use, indentation
178 should be expected.
179 .SH "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED"
180 .IX Header "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED"
181 This is a list of cpan modules that have been known to have been broken by the
182 upgrade at one point.
183 .SS "WORKS BUT TESTS WILL FAIL"
184 .IX Subsection "WORKS BUT TESTS WILL FAIL"
185 These modules still function correctly, but their test suites will not pass. If
186 you already have these modules installed then you can continue to use them. If
187 you are trying to install them after upgrading Test::Builder you will need to
188 force installation, or bypass the broken tests.
189 .IP Test::DBIx::Class::Schema 4
190 .IX Item "Test::DBIx::Class::Schema"
191 This module has a test that appears to work around a Test::Builder bug. The bug
192 appears to have been fixed by Test2, which means the workaround causes a
193 failure. This can be easily updated, but nobody has done so yet.
194 .Sp
195 Known broken in versions: 1.0.9 and older
196 .IP Device::Chip 4
197 .IX Item "Device::Chip"
198 Tests break due to subtest indentation.
199 .Sp
200 Known broken in version 0.07. Apparently works fine in 0.06 though. Patch has
201 been submitted to fix the issue.
202 .SS "UPGRADE SUGGESTED"
203 .IX Subsection "UPGRADE SUGGESTED"
204 These are modules that did not break, but had broken test suites that have
205 since been fixed.
206 .IP Test::Exception 4
207 .IX Item "Test::Exception"
208 Old versions work fine, but have a minor test name behavior that breaks with
209 Test2. Old versions will no longer install because of this. The latest version
210 on CPAN will install just fine. Upgrading is not required, but is recommended.
211 .Sp
212 Fixed in version: 0.43
213 .IP Data::Peek 4
214 .IX Item "Data::Peek"
215 Some tests depended on \f(CW$!\fR and \f(CW$?\fR being modified in subtle ways. A patch
216 was applied to correct things that changed.
217 .Sp
218 The module itself works fine, there is no need to upgrade.
219 .Sp
220 Fixed in version: 0.45
221 .IP circular::require 4
222 .IX Item "circular::require"
223 Some tests were fragile and required base.pm to be loaded at a late stage.
224 Test2 was loading base.pm too early. The tests were updated to fix this.
225 .Sp
226 The module itself never broke, you do not need to upgrade.
227 .Sp
228 Fixed in version: 0.12
229 .IP Test::Module::Used 4
230 .IX Item "Test::Module::Used"
231 A test worked around a now\-fixed planning bug. There is no need to upgrade if
232 you have an old version installed. New versions install fine if you want them.
233 .Sp
234 Fixed in version: 0.2.5
235 .IP Test::Moose::More 4
236 .IX Item "Test::Moose::More"
237 Some tests were fragile, but have been fixed. The actual breakage was from the
238 subtest comment indentation change.
239 .Sp
240 No need to upgrade, old versions work fine. Only new versions will install.
241 .Sp
242 Fixed in version: 0.025
243 .IP Test::FITesque 4
244 .IX Item "Test::FITesque"
245 This was broken by a bugfix to how planning is done. The test was updated after
246 the bugfix.
247 .Sp
248 Fixed in version: 0.04
249 .IP Test::Kit 4
250 .IX Item "Test::Kit"
251 Old versions work fine, but would not install because Test::Aggregate was in
252 the dependency chain. An upgrade should not be needed.
253 .Sp
254 Fixed in version: 2.15
255 .IP autouse 4
256 .IX Item "autouse"
257 A test broke because it depended on Scalar::Util not being loaded. Test2 loads
258 Scalar::Util. The test was updated to load Test2 after checking Scalar::Util\*(Aqs
259 load status.
260 .Sp
261 There is no need to upgrade if you already have it installed.
262 .Sp
263 Fixed in version: 1.11
264 .SS "NEED TO UPGRADE"
265 .IX Subsection "NEED TO UPGRADE"
266 .IP Test::SharedFork 4
267 .IX Item "Test::SharedFork"
268 Old versions need to directly access Test::Builder singleton hash elements. The
269 latest version on CPAN will still do this on old Test::Builder, but will defer
270 to Test2::IPC on Test2.
271 .Sp
272 Fixed in version: 0.35
273 .IP Test::Builder::Clutch 4
274 .IX Item "Test::Builder::Clutch"
275 This works by doing overriding methods on the singleton, and directly accessing
276 hash values on the singleton. A new version has been released that uses the
277 Test2 API to accomplish the same result in a saner way.
278 .Sp
279 Fixed in version: 0.07
280 .IP Test::Dist::VersionSync 4
281 .IX Item "Test::Dist::VersionSync"
282 This had Test::Builder2 conditionals. This was fixed by removing the
283 conditionals.
284 .Sp
285 Fixed in version: 1.1.4
286 .IP Test::Modern 4
287 .IX Item "Test::Modern"
288 This relied on \f(CW\*(C`Test::Builder\->_try()\*(C'\fR which was a private method,
289 documented as something nobody should use. This was fixed by using a different
290 tool.
291 .Sp
292 Fixed in version: 0.012
293 .IP Test::UseAllModules 4
294 .IX Item "Test::UseAllModules"
295 Version 0.14 relied on \f(CW\*(C`Test::Builder\->history\*(C'\fR which was available in
296 Test::Builder 1.5. Versions 0.12 and 0.13 relied on other Test::Builder
297 internals.
298 .Sp
299 Fixed in version: 0.15
300 .IP Test::More::Prefix 4
301 .IX Item "Test::More::Prefix"
302 Worked by applying a role that wrapped \f(CW\*(C`Test::Builder\->_print_comment\*(C'\fR.
303 Fixed by adding an event filter that modifies the message instead when running
304 under Test2.
305 .Sp
306 Fixed in version: 0.007
307 .SS "STILL BROKEN"
308 .IX Subsection "STILL BROKEN"
309 .IP Test::Aggregate 4
310 .IX Item "Test::Aggregate"
311 This distribution directly accesses the hash keys in the Test::Builder
312 singleton. It also approaches the problem from the wrong angle, please consider
313 using Test2::Aggregate for similar functionality and Test2::Harness
314 which allows module preloading at the harness level.
315 .Sp
316 Still broken as of version: 0.373
317 .IP Test::Wrapper 4
318 .IX Item "Test::Wrapper"
319 This module directly uses hash keys in the Test::Builder singleton. This
320 module is also obsolete thanks to the benefits of Test2. Use \f(CWintercept()\fR
321 from Test2::API to achieve a similar result.
322 .Sp
323 Still broken as of version: 0.3.0
324 .IP Test::ParallelSubtest 4
325 .IX Item "Test::ParallelSubtest"
326 This module overrides \f(CWTest::Builder::subtest()\fR and
327 \&\f(CWTest::Builder::done_testing()\fR. It also directly accesses hash elements of
328 the singleton. It has not yet been fixed.
329 .Sp
330 Alternatives: Test2::AsyncSubtest and Test2::Workflow (not stable).
331 .Sp
332 Still broken as of version: 0.05
333 .IP Test::Pretty 4
334 .IX Item "Test::Pretty"
335 See <https://github.com/tokuhirom/Test\-Pretty/issues/25>
336 .Sp
337 The author admits the module is crazy, and he is awaiting a stable release of
338 something new (Test2) to completely rewrite it in a sane way.
339 .Sp
340 Still broken as of version: 0.32
341 .IP Net::BitTorrent 4
342 .IX Item "Net::BitTorrent"
343 The tests for this module directly access Test::Builder hash keys. Most, if
344 not all of these hash keys have public API methods that could be used instead
345 to avoid the problem.
346 .Sp
347 Still broken in version: 0.052
348 .IP Test::Group 4
349 .IX Item "Test::Group"
350 It monkeypatches Test::Builder, and calls it "black magic" in the code.
351 .Sp
352 Still broken as of version: 0.20
353 .IP Test::Flatten 4
354 .IX Item "Test::Flatten"
355 This modifies the Test::Builder internals in many ways. A better was to
356 accomplish the goal of this module is to write your own subtest function.
357 .Sp
358 Still broken as of version: 0.11
359 .IP Log::Dispatch::Config::TestLog 4
360 .IX Item "Log::Dispatch::Config::TestLog"
361 Modifies Test::Builder internals.
362 .Sp
363 Still broken as of version: 0.02
364 .IP Test::Able 4
365 .IX Item "Test::Able"
366 Modifies Test::Builder internals.
367 .Sp
368 Still broken as of version: 0.11
369 .SH "MAKE ASSERTIONS \-> SEND EVENTS"
370 .IX Header "MAKE ASSERTIONS -> SEND EVENTS"
371 .SS LEGACY
372 .IX Subsection "LEGACY"
373 .Vb 1
374 \& use Test::Builder;
375 \&
376 \& # A majority of tools out there do this:
377 \& # my $TB = Test::Builder\->new;
378 \& # This works, but has always been wrong, forcing Test::Builder to implement
379 \& # subtests as a horrific hack. It also causes problems for tools that try
380 \& # to replace the singleton (also discouraged).
381 \&
382 \& sub my_ok($;$) {
383 \& my ($bool, $name) = @_;
384 \& my $TB = Test::Builder\->new;
385 \& $TB\->ok($bool, $name);
386 \& }
387 \&
388 \& sub my_diag($) {
389 \& my ($msg) = @_;
390 \& my $TB = Test::Builder\->new;
391 \& $TB\->diag($msg);
392 \& }
393 .Ve
394 .SS TEST2
395 .IX Subsection "TEST2"
396 .Vb 1
397 \& use Test2::API qw/context/;
398 \&
399 \& sub my_ok($;$) {
400 \& my ($bool, $name) = @_;
401 \& my $ctx = context();
402 \& $ctx\->ok($bool, $name);
403 \& $ctx\->release;
404 \& }
405 \&
406 \& sub my_diag($) {
407 \& my ($msg) = @_;
408 \& my $ctx = context();
409 \& $ctx\->diag($msg);
410 \& $ctx\->release;
411 \& }
412 .Ve
413 .PP
414 The context object has API compatible implementations of the following methods:
415 .ie n .IP "ok($bool, $name)" 4
416 .el .IP "ok($bool, \f(CW$name\fR)" 4
417 .IX Item "ok($bool, $name)"
418 .PD 0
419 .IP diag(@messages) 4
420 .IX Item "diag(@messages)"
421 .IP note(@messages) 4
422 .IX Item "note(@messages)"
423 .ie n .IP "subtest($name, $code)" 4
424 .el .IP "subtest($name, \f(CW$code\fR)" 4
425 .IX Item "subtest($name, $code)"
426 .PD
427 .PP
428 If you are looking for helpers with \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`like\*(C'\fR, and others, see
429 Test2::Suite.
430 .SH "WRAP EXISTING TOOLS"
431 .IX Header "WRAP EXISTING TOOLS"
432 .SS LEGACY
433 .IX Subsection "LEGACY"
434 .Vb 1
435 \& use Test::More;
436 \&
437 \& sub exclusive_ok {
438 \& my ($bool1, $bool2, $name) = @_;
439 \&
440 \& # Ensure errors are reported 1 level higher
441 \& local $Test::Builder::Level = $Test::Builder::Level + 1;
442 \&
443 \& $ok = $bool1 || $bool2;
444 \& $ok &&= !($bool1 && $bool2);
445 \& ok($ok, $name);
446 \&
447 \& return $bool;
448 \& }
449 .Ve
450 .PP
451 Every single tool in the chain from this, to \f(CW\*(C`ok\*(C'\fR, to anything \f(CW\*(C`ok\*(C'\fR calls
452 needs to increment the \f(CW$Level\fR variable. When an error occurs Test::Builder
453 will do a trace to the stack frame determined by \f(CW$Level\fR, and report that
454 file+line as the one where the error occurred. If you or any other tool you use
455 forgets to set \f(CW$Level\fR then errors will be reported to the wrong place.
456 .SS TEST2
457 .IX Subsection "TEST2"
458 .Vb 1
459 \& use Test::More;
460 \&
461 \& sub exclusive_ok {
462 \& my ($bool1, $bool2, $name) = @_;
463 \&
464 \& # Grab and store the context, even if you do not need to use it
465 \& # directly.
466 \& my $ctx = context();
467 \&
468 \& $ok = $bool1 || $bool2;
469 \& $ok &&= !($bool1 && $bool2);
470 \& ok($ok, $name);
471 \&
472 \& $ctx\->release;
473 \& return $bool;
474 \& }
475 .Ve
476 .PP
477 Instead of using \f(CW$Level\fR to perform a backtrace, Test2 uses a context
478 object. In this sample you create a context object and store it. This locks the
479 context (errors report 1 level up from here) for all wrapped tools to find. You
480 do not need to use the context object, but you do need to store it in a
481 variable. Once the sub ends the \f(CW$ctx\fR variable is destroyed which lets future
482 tools find their own.
483 .SH "USING UTF8"
484 .IX Header "USING UTF8"
485 .SS LEGACY
486 .IX Subsection "LEGACY"
487 .Vb 3
488 \& # Set the mode BEFORE anything loads Test::Builder
489 \& use open \*(Aq:std\*(Aq, \*(Aq:encoding(utf8)\*(Aq;
490 \& use Test::More;
491 .Ve
492 .PP
493 Or
494 .PP
495 .Vb 5
496 \& # Modify the filehandles
497 \& my $builder = Test::More\->builder;
498 \& binmode $builder\->output, ":encoding(utf8)";
499 \& binmode $builder\->failure_output, ":encoding(utf8)";
500 \& binmode $builder\->todo_output, ":encoding(utf8)";
501 .Ve
502 .SS TEST2
503 .IX Subsection "TEST2"
504 .Vb 1
505 \& use Test2::API qw/test2_stack/;
506 \&
507 \& test2_stack\->top\->format\->encoding(\*(Aqutf8\*(Aq);
508 .Ve
509 .PP
510 Though a much better way is to use the Test2::Plugin::UTF8 plugin, which is
511 part of Test2::Suite.
512 .SH "AUTHORS, CONTRIBUTORS AND REVIEWERS"
513 .IX Header "AUTHORS, CONTRIBUTORS AND REVIEWERS"
514 The following people have all contributed to this document in some way, even if
515 only for review.
516 .IP "Chad Granum (EXODIST) <[email protected]>" 4
517 .IX Item "Chad Granum (EXODIST) <[email protected]>"
518 .SH SOURCE
519 .IX Header "SOURCE"
520 The source code repository for Test2 can be found at
521 <https://github.com/Test\-More/test\-more/>.
522 .SH MAINTAINER
523 .IX Header "MAINTAINER"
524 .IP "Chad Granum <[email protected]>" 4
525 .IX Item "Chad Granum <[email protected]>"
526 .SH COPYRIGHT
527 .IX Header "COPYRIGHT"
528 Copyright Chad Granum <[email protected]>.
529 .PP
530 This program is free software; you can redistribute it and/or
531 modify it under the same terms as Perl itself.
532 .PP
533 See <https://dev.perl.org/licenses/>