1Test2::Transition(3)  User Contributed Perl Documentation Test2::Transition(3)
2
3
4

NAME

6       Test2::Transition - Transition notes when upgrading to Test2
7

DESCRIPTION

9       This is where gotchas and breakages related to the Test2 upgrade are
10       documented. The upgrade causes Test::Builder to defer to Test2 under
11       the hood.  This transition is mostly transparent, but there are a few
12       cases that can trip you up.
13

THINGS THAT BREAK

15       This is the list of scenarios that break with the new internals.
16
17   Test::Builder1.5/2 conditionals
18       The Problem
19
20       a few years back there were two attempts to upgrade/replace
21       Test::Builder.  Confusingly these were called Test::Builder2 and
22       Test::Builder1.5, in that order. Many people put conditionals in their
23       code to check the Test::Builder version number and adapt their code
24       accordingly.
25
26       The Test::Builder2/1.5 projects both died out. Now the conditional code
27       people added has become a mine field. A vast majority of modules broken
28       by Test2 fall into this category.
29
30       The Fix
31
32       The fix is to remove all Test::Builder1.5/2 related code. Either use
33       the legacy Test::Builder API, or use Test2 directly.
34
35   Replacing the Test::Builder singleton
36       The Problem
37
38       Some test modules would replace the Test::Builder singleton instance
39       with their own instance or subclass. This was usually done to intercept
40       or modify results as they happened.
41
42       The Test::Builder singleton is now a simple compatibility wrapper
43       around Test2. The Test::Builder singleton is no longer the central
44       place for results. Many results bypass the Test::Builder singleton
45       completely, which breaks and behavior intended when replacing the
46       singleton.
47
48       The Fix
49
50       If you simply want to intercept all results instead of letting them go
51       to TAP, you should look at the Test2::API docs and read about pushing a
52       new hub onto the hub stack. Replacing the hub temporarily is now the
53       correct way to intercept results.
54
55       If your goal is purely monitoring of events use the
56       "Test2::Hub->listen()" method exported by Test::More to watch events as
57       they are fired. If you wish to modify results before they go to TAP
58       look at the "Test2::Hub->filter()" method.
59
60   Directly Accessing Hash Elements
61       The Problem
62
63       Some modules look directly at hash keys on the Test::Builder singleton.
64       The problem here is that the Test::Builder singleton no longer holds
65       anything important.
66
67       The Fix
68
69       The fix is to use the API specified in Test2::API to look at or modify
70       state as needed.
71
72   Subtest indentation
73       The Problem
74
75       An early change, in fact the change that made Test2 an idea, was a
76       change to the indentation of the subtest note. It was decided it would
77       be more readable to outdent the subtest note instead of having it
78       inline with the subtest:
79
80           # subtest foo
81               ok 1 - blah
82               1..1
83           ok 1 - subtest foo
84
85       The old style indented the note:
86
87               # subtest foo
88               ok 1 - blah
89               1..1
90           ok 1 - subtest foo
91
92       This breaks tests that do string comparison of TAP output.
93
94       The Fix
95
96           my $indent = $INC{'Test2/API.pm'} ? '' : '    ';
97
98           is(
99               $subtest_output,
100               "${indent}# subtest foo",
101               "Got subtest note"
102           );
103
104       Check if $INC{'Test2/API.pm'} is set, if it is then no indentation
105       should be expected. If it is not set, then the old Test::Builder is in
106       use, indentation should be expected.
107

DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED

109       This is a list of cpan modules that have been known to have been broken
110       by the upgrade at one point.
111
112   WORKS BUT TESTS WILL FAIL
113       These modules still function correctly, but their test suites will not
114       pass. If you already have these modules installed then you can continue
115       to use them. If you are trying to install them after upgrading
116       Test::Builder you will need to force installation, or bypass the broken
117       tests.
118
119       Test::DBIx::Class::Schema
120           This module has a test that appears to work around a Test::Builder
121           bug. The bug appears to have been fixed by Test2, which means the
122           workaround causes a failure. This can be easily updated, but nobody
123           has done so yet.
124
125           Known broken in versions: 1.0.9 and older
126
127       Device::Chip
128           Tests break due to subtest indentation.
129
130           Known broken in version 0.07. Apparently works fine in 0.06 though.
131           Patch has been submitted to fix the issue.
132
133   UPGRADE SUGGESTED
134       These are modules that did not break, but had broken test suites that
135       have since been fixed.
136
137       Test::Exception
138           Old versions work fine, but have a minor test name behavior that
139           breaks with Test2. Old versions will no longer install because of
140           this. The latest version on CPAN will install just fine. Upgrading
141           is not required, but is recommended.
142
143           Fixed in version: 0.43
144
145       Data::Peek
146           Some tests depended on $! and $? being modified in subtle ways. A
147           patch was applied to correct things that changed.
148
149           The module itself works fine, there is no need to upgrade.
150
151           Fixed in version: 0.45
152
153       circular::require
154           Some tests were fragile and required base.pm to be loaded at a late
155           stage.  Test2 was loading base.pm too early. The tests were updated
156           to fix this.
157
158           The module itself never broke, you do not need to upgrade.
159
160           Fixed in version: 0.12
161
162       Test::Module::Used
163           A test worked around a now-fixed planning bug. There is no need to
164           upgrade if you have an old version installed. New versions install
165           fine if you want them.
166
167           Fixed in version: 0.2.5
168
169       Test::Moose::More
170           Some tests were fragile, but have been fixed. The actual breakage
171           was from the subtest comment indentation change.
172
173           No need to upgrade, old versions work fine. Only new versions will
174           install.
175
176           Fixed in version: 0.025
177
178       Test::FITesque
179           This was broken by a bugfix to how planning is done. The test was
180           updated after the bugfix.
181
182           Fixed in version: 0.04
183
184       Test::Kit
185           Old versions work fine, but would not install because
186           Test::Aggregate was in the dependency chain. An upgrade should not
187           be needed.
188
189           Fixed in version: 2.15
190
191       autouse
192           A test broke because it depended on Scalar::Util not being loaded.
193           Test2 loads Scalar::Util. The test was updated to load Test2 after
194           checking Scalar::Util's load status.
195
196           There is no need to upgrade if you already have it installed.
197
198           Fixed in version: 1.11
199
200   NEED TO UPGRADE
201       Test::SharedFork
202           Old versions need to directly access Test::Builder singleton hash
203           elements. The latest version on CPAN will still do this on old
204           Test::Builder, but will defer to Test2::IPC on Test2.
205
206           Fixed in version: 0.35
207
208       Test::Builder::Clutch
209           This works by doing overriding methods on the singleton, and
210           directly accessing hash values on the singleton. A new version has
211           been released that uses the Test2 API to accomplish the same result
212           in a saner way.
213
214           Fixed in version: 0.07
215
216       Test::Dist::VersionSync
217           This had Test::Builder2 conditionals. This was fixed by removing
218           the conditionals.
219
220           Fixed in version: 1.1.4
221
222       Test::Modern
223           This relied on "Test::Builder->_try()" which was a private method,
224           documented as something nobody should use. This was fixed by using
225           a different tool.
226
227           Fixed in version: 0.012
228
229       Test::UseAllModules
230           Version 0.14 relied on "Test::Builder->history" which was available
231           in Test::Builder 1.5. Versions 0.12 and 0.13 relied on other
232           Test::Builder internals.
233
234           Fixed in version: 0.15
235
236       Test::More::Prefix
237           Worked by applying a role that wrapped
238           "Test::Builder->_print_comment".  Fixed by adding an event filter
239           that modifies the message instead when running under Test2.
240
241           Fixed in version: 0.007
242
243   STILL BROKEN
244       Test::Aggregate
245           This distribution directly accesses the hash keys in the
246           Test::Builder singleton. It also approaches the problem from the
247           wrong angle, please consider using Test2::Aggregate for similar
248           functionality and Test2::Harness which allows module preloading at
249           the harness level.
250
251           Still broken as of version: 0.373
252
253       Test::Wrapper
254           This module directly uses hash keys in the Test::Builder singleton.
255           This module is also obsolete thanks to the benefits of Test2. Use
256           "intercept()" from Test2::API to achieve a similar result.
257
258           Still broken as of version: 0.3.0
259
260       Test::ParallelSubtest
261           This module overrides "Test::Builder::subtest()" and
262           "Test::Builder::done_testing()". It also directly accesses hash
263           elements of the singleton. It has not yet been fixed.
264
265           Alternatives: Test2::AsyncSubtest and Test2::Workflow (not stable).
266
267           Still broken as of version: 0.05
268
269       Test::Pretty
270           See https://github.com/tokuhirom/Test-Pretty/issues/25
271
272           The author admits the module is crazy, and he is awaiting a stable
273           release of something new (Test2) to completely rewrite it in a sane
274           way.
275
276           Still broken as of version: 0.32
277
278       Net::BitTorrent
279           The tests for this module directly access Test::Builder hash keys.
280           Most, if not all of these hash keys have public API methods that
281           could be used instead to avoid the problem.
282
283           Still broken in version: 0.052
284
285       Test::Group
286           It monkeypatches Test::Builder, and calls it "black magic" in the
287           code.
288
289           Still broken as of version: 0.20
290
291       Test::Flatten
292           This modifies the Test::Builder internals in many ways. A better
293           was to accomplish the goal of this module is to write your own
294           subtest function.
295
296           Still broken as of version: 0.11
297
298       Log::Dispatch::Config::TestLog
299           Modifies Test::Builder internals.
300
301           Still broken as of version: 0.02
302
303       Test::Able
304           Modifies Test::Builder internals.
305
306           Still broken as of version: 0.11
307

MAKE ASSERTIONS -> SEND EVENTS

309   LEGACY
310           use Test::Builder;
311
312           # A majority of tools out there do this:
313           # my $TB = Test::Builder->new;
314           # This works, but has always been wrong, forcing Test::Builder to implement
315           # subtests as a horrific hack. It also causes problems for tools that try
316           # to replace the singleton (also discouraged).
317
318           sub my_ok($;$) {
319               my ($bool, $name) = @_;
320               my $TB = Test::Builder->new;
321               $TB->ok($bool, $name);
322           }
323
324           sub my_diag($) {
325               my ($msg) = @_;
326               my $TB = Test::Builder->new;
327               $TB->diag($msg);
328           }
329
330   TEST2
331           use Test2::API qw/context/;
332
333           sub my_ok($;$) {
334               my ($bool, $name) = @_;
335               my $ctx = context();
336               $ctx->ok($bool, $name);
337               $ctx->release;
338           }
339
340           sub my_diag($) {
341               my ($msg) = @_;
342               my $ctx = context();
343               $ctx->diag($msg);
344               $ctx->release;
345           }
346
347       The context object has API compatible implementations of the following
348       methods:
349
350       ok($bool, $name)
351       diag(@messages)
352       note(@messages)
353       subtest($name, $code)
354
355       If you are looking for helpers with "is", "like", and others, see
356       Test2::Suite.
357

WRAP EXISTING TOOLS

359   LEGACY
360           use Test::More;
361
362           sub exclusive_ok {
363               my ($bool1, $bool2, $name) = @_;
364
365               # Ensure errors are reported 1 level higher
366               local $Test::Builder::Level = $Test::Builder::Level + 1;
367
368               $ok = $bool1 || $bool2;
369               $ok &&= !($bool1 && $bool2);
370               ok($ok, $name);
371
372               return $bool;
373           }
374
375       Every single tool in the chain from this, to "ok", to anything "ok"
376       calls needs to increment the $Level variable. When an error occurs
377       Test::Builder will do a trace to the stack frame determined by $Level,
378       and report that file+line as the one where the error occurred. If you
379       or any other tool you use forgets to set $Level then errors will be
380       reported to the wrong place.
381
382   TEST2
383           use Test::More;
384
385           sub exclusive_ok {
386               my ($bool1, $bool2, $name) = @_;
387
388               # Grab and store the context, even if you do not need to use it
389               # directly.
390               my $ctx = context();
391
392               $ok = $bool1 || $bool2;
393               $ok &&= !($bool1 && $bool2);
394               ok($ok, $name);
395
396               $ctx->release;
397               return $bool;
398           }
399
400       Instead of using $Level to perform a backtrace, Test2 uses a context
401       object. In this sample you create a context object and store it. This
402       locks the context (errors report 1 level up from here) for all wrapped
403       tools to find. You do not need to use the context object, but you do
404       need to store it in a variable. Once the sub ends the $ctx variable is
405       destroyed which lets future tools find their own.
406

USING UTF8

408   LEGACY
409           # Set the mode BEFORE anything loads Test::Builder
410           use open ':std', ':encoding(utf8)';
411           use Test::More;
412
413       Or
414
415           # Modify the filehandles
416           my $builder = Test::More->builder;
417           binmode $builder->output,         ":encoding(utf8)";
418           binmode $builder->failure_output, ":encoding(utf8)";
419           binmode $builder->todo_output,    ":encoding(utf8)";
420
421   TEST2
422           use Test2::API qw/test2_stack/;
423
424           test2_stack->top->format->encoding('utf8');
425
426       Though a much better way is to use the Test2::Plugin::UTF8 plugin,
427       which is part of Test2::Suite.
428

AUTHORS, CONTRIBUTORS AND REVIEWERS

430       The following people have all contributed to this document in some way,
431       even if only for review.
432
433       Chad Granum (EXODIST) <exodist@cpan.org>
434

SOURCE

436       The source code repository for Test2 can be found at
437       http://github.com/Test-More/test-more/.
438

MAINTAINER

440       Chad Granum <exodist@cpan.org>
441
443       Copyright 2020 Chad Granum <exodist@cpan.org>.
444
445       This program is free software; you can redistribute it and/or modify it
446       under the same terms as Perl itself.
447
448       See http://www.perl.com/perl/misc/Artistic.html
449
450
451
452perl v5.36.0                      2022-07-22              Test2::Transition(3)
Impressum