1Test2::Transition(3) User Contributed Perl Documentation Test2::Transition(3)
2
6 Test2::Transition - Transition notes when upgrading to Test2
7
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
15 This is the list of scenarios that break with the new internals.
16 Test::Builder1.5/2 conditionals
18 The Problem
19 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 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 The Fix
31 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 Replacing the Test::Builder singleton
36 The Problem
37 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 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 The Fix
49 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 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 Directly Accessing Hash Elements
61 The Problem
62 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 The Fix
68 The fix is to use the API specified in Test2::API to look at or modify
70 state as needed.
71 Subtest indentation
73 The Problem
74 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 # subtest foo
81 ok 1 - blah
82 1..1
83 ok 1 - subtest foo
84 The old style indented the note:
86 # subtest foo
88 ok 1 - blah
89 1..1
90 ok 1 - subtest foo
91 This breaks tests that do string comparison of TAP output.
93 The Fix
95 my $indent = $INC{'Test2/API.pm'} ? '' : ' ';
97 is(
99 $subtest_output,
100 "${indent}# subtest foo",
101 "Got subtest note"
102 );
103 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
109 This is a list of cpan modules that have been known to have been broken
110 by the upgrade at one point.
111 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 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 Known broken in versions: 1.0.9 and older
126 Device::Chip
128 Tests break due to subtest indentation.
129 Known broken in version 0.07. Apparently works fine in 0.06 though.
131 Patch has been submitted to fix the issue.
132 UPGRADE SUGGESTED
134 These are modules that did not break, but had broken test suites that
135 have since been fixed.
136 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 Fixed in version: 0.43
144 Data::Peek
146 Some tests depended on $! and $? being modified in subtle ways. A
147 patch was applied to correct things that changed.
148 The module itself works fine, there is no need to upgrade.
150 Fixed in version: 0.45
152 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 The module itself never broke, you do not need to upgrade.
159 Fixed in version: 0.12
161 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 Fixed in version: 0.2.5
168 Test::Moose::More
170 Some tests were fragile, but have been fixed. The actual breakage
171 was from the subtest comment indentation change.
172 No need to upgrade, old versions work fine. Only new versions will
174 install.
175 Fixed in version: 0.025
177 Test::FITesque
179 This was broken by a bugfix to how planning is done. The test was
180 updated after the bugfix.
181 Fixed in version: 0.04
183 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 Fixed in version: 2.15
190 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 There is no need to upgrade if you already have it installed.
197 Fixed in version: 1.11
199 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 Fixed in version: 0.35
207 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 Fixed in version: 0.07
215 Test::Dist::VersionSync
217 This had Test::Builder2 conditionals. This was fixed by removing
218 the conditionals.
219 Fixed in version: 1.1.4
221 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 Fixed in version: 0.012
228 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 Fixed in version: 0.15
235 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 Fixed in version: 0.007
242 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 Still broken as of version: 0.373
252 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 Still broken as of version: 0.3.0
259 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 Alternatives: Test2::AsyncSubtest and Test2::Workflow (not stable).
266 Still broken as of version: 0.05
268 Test::Pretty
270 See https://github.com/tokuhirom/Test-Pretty/issues/25
271 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 Still broken as of version: 0.32
277 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 Still broken in version: 0.052
284 Test::Group
286 It monkeypatches Test::Builder, and calls it "black magic" in the
287 code.
288 Still broken as of version: 0.20
290 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 Still broken as of version: 0.11
297 Log::Dispatch::Config::TestLog
299 Modifies Test::Builder internals.
300 Still broken as of version: 0.02
302 Test::Able
304 Modifies Test::Builder internals.
305 Still broken as of version: 0.11
307
309 LEGACY
310 use Test::Builder;
311 # 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 sub my_ok($;$) {
319 my ($bool, $name) = @_;
320 my $TB = Test::Builder->new;
321 $TB->ok($bool, $name);
322 }
323 sub my_diag($) {
325 my ($msg) = @_;
326 my $TB = Test::Builder->new;
327 $TB->diag($msg);
328 }
329 TEST2
331 use Test2::API qw/context/;
332 sub my_ok($;$) {
334 my ($bool, $name) = @_;
335 my $ctx = context();
336 $ctx->ok($bool, $name);
337 $ctx->release;
338 }
339 sub my_diag($) {
341 my ($msg) = @_;
342 my $ctx = context();
343 $ctx->diag($msg);
344 $ctx->release;
345 }
346 The context object has API compatible implementations of the following
348 methods:
349 ok($bool, $name)
351 diag(@messages)
352 note(@messages)
353 subtest($name, $code)
354 If you are looking for helpers with "is", "like", and others, see
356 Test2::Suite.
357
359 LEGACY
360 use Test::More;
361 sub exclusive_ok {
363 my ($bool1, $bool2, $name) = @_;
364 # Ensure errors are reported 1 level higher
366 local $Test::Builder::Level = $Test::Builder::Level + 1;
367 $ok = $bool1 || $bool2;
369 $ok &&= !($bool1 && $bool2);
370 ok($ok, $name);
371 return $bool;
373 }
374 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 TEST2
383 use Test::More;
384 sub exclusive_ok {
386 my ($bool1, $bool2, $name) = @_;
387 # Grab and store the context, even if you do not need to use it
389 # directly.
390 my $ctx = context();
391 $ok = $bool1 || $bool2;
393 $ok &&= !($bool1 && $bool2);
394 ok($ok, $name);
395 $ctx->release;
397 return $bool;
398 }
399 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
408 LEGACY
409 # Set the mode BEFORE anything loads Test::Builder
410 use open ':std', ':encoding(utf8)';
411 use Test::More;
412 Or
414 # 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 TEST2
422 use Test2::API qw/test2_stack/;
423 test2_stack->top->format->encoding('utf8');
425 Though a much better way is to use the Test2::Plugin::UTF8 plugin,
427 which is part of Test2::Suite.
428
430 The following people have all contributed to this document in some way,
431 even if only for review.
432 Chad Granum (EXODIST) <exodist@cpan.org>
434
436 The source code repository for Test2 can be found at
437 http://github.com/Test-More/test-more/.
438
440 Chad Granum <exodist@cpan.org>
441
443 Copyright 2020 Chad Granum <exodist@cpan.org>.
444 This program is free software; you can redistribute it and/or modify it
446 under the same terms as Perl itself.
447 See http://www.perl.com/perl/misc/Artistic.html
449perl v5.34.0 2021-09-29 Test2::Transition(3)