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

MAKE ASSERTIONS -> SEND EVENTS

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

WRAP EXISTING TOOLS

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

USING UTF8

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

AUTHORS, CONTRIBUTORS AND REVIEWERS

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

SOURCE

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

MAINTAINER

438       Chad Granum <exodist@cpan.org>
439
441       Copyright 2019 Chad Granum <exodist@cpan.org>.
442
443       This program is free software; you can redistribute it and/or modify it
444       under the same terms as Perl itself.
445
446       See http://www.perl.com/perl/misc/Artistic.html
447
448
449
450perl v5.28.1                      2019-02-06              Test2::Transition(3)
Impressum