| Test2::Transition - Transition notes when upgrading to Test2 |
Test2::Transition - Transition notes when upgrading to Test2
This is where gotchas and breakages related to the Test2 upgrade are documented. The upgrade causes Test::Builder to defer to Test2 under the hood. This transition is mostly transparent, but there are a few cases that can trip you up.
This is the list of scenarios that break with the new internals.
a few years back there were two attempts to upgrade/replace Test::Builder. Confusingly these were called Test::Builder2 and Test::Builder1.5, in that order. Many people put conditionals in their code to check the Test::Builder version number and adapt their code accordingly.
The Test::Builder2/1.5 projects both died out. Now the conditional code people added has become a mine field. A vast majority of modules broken by Test2 fall into this category.
The fix is to remove all Test::Builder1.5/2 related code. Either use the legacy Test::Builder API, or use Test2 directly.
Some test modules would replace the Test::Builder singleton instance with their own instance or subclass. This was usually done to intercept or modify results as they happened.
The Test::Builder singleton is now a simple compatibility wrapper around Test2. The Test::Builder singleton is no longer the central place for results. Many results bypass the Test::Builder singleton completely, which breaks and behavior intended when replacing the singleton.
If you simply want to intercept all results instead of letting them go to TAP, you should look at the the Test2::API manpage docs and read about pushing a new hub onto the hub stack. Replacing the hub temporarily is now the correct way to intercept results.
If your goal is purely monitoring of events use the Test2::Hub->listen()
method exported by Test::More to watch events as they are fired. If you wish to
modify results before they go to TAP look at the Test2::Hub->filter()
method.
Some modules look directly at hash keys on the Test::Builder singleton. The problem here is that the Test::Builder singleton no longer holds anything important.
The fix is to use the API specified in the Test2::API manpage to look at or modify state as needed.
An early change, in fact the change that made Test2 an idea, was a change to the indentation of the subtest note. IT was decided it would be more readable to outdent the subtest note instead of having it inline with the subtest:
# subtest foo
ok 1 - blah
1..1
ok 1 - subtest foo
The old style indented the note:
# subtest foo
ok 1 - blah
1..1
ok 1 - subtest foo
This breaks tests that do string comparison of TAP output.
my $indent = $INC{'Test2/API.pm'} ? '' : ' ';
is(
$subtest_output,
"${indent}# subtest foo",
"Got subtest note"
);
Check if $INC{'Test2/API.pm'} is set, if it is then no indentation should be
expected. If it is not set than the old Test::Builder is in use, indentation
should be expected.
This is a list of cpan modules that have been known to have been broken by the upgrade at one point.
These modules still function correctly, but their test suites will not pass. If you already have these modules installed then you can continue to use them. If you are trying to install them after upgrading Test::Builder you will need to force installation, or bypass the broken tests.
Known broken in versions: 1.0.9 and older
See the the Test::Aggregate manpage info below for additional information.
Known broken in version 0.07. Apparently works fine in 0.06 though. Patch has been submitted to fix the issue.
These are modules that did not break, but had broken test suites that have since been fixed.
Fixed in version: 0.43
$! and $? being modified in subtle ways. A patch
was applied to correct things that changed.
The module itself works fine, there is no need to upgrade.
Fixed in version: 0.45
The module itself never broke, you do not need to upgrade.
Fixed in version: 0.12
Fixed in version: 0.2.5
No need to upgrade, old versions work fine. Only new versions will install.
Fixed in version: 0.025
Fixed in version: 0.04
There is no need to upgrade if you already have it installed.
Fixed in version: 1.11
Fixed in version: 0.35
Fixed in version: 0.07
Fixed in version: 1.1.4
Test::Builder->_try() which was a private method,
documented as something nobody should use. This was fixed by using a different
tool.
Fixed in version: 0.012
Test::Builder->history which was available in
Test::Builder 1.5. Versions 0.12 and 0.13 relied on other Test::Builder
internals.
Fixed in version: 0.15
Test::Builder->_print_comment.
Fixed by adding an event filter that modifies the message instead when running
under Test2.
Fixed in version: 0.007
Still broken as of version: 0.373
intercept()
from the Test2::API manpage to achieve a similar result.
Still broken as of version: 0.3.0
Test::Builder::subtest() and
Test::Builder::done_testing(). It also directly accesses hash elements of
the singleton. It has not yet been fixed.
Alternatives: the Test2::AsyncSubtest manpage and the Test2::Workflow manpage (not stable).
Still broken as of version: 0.05
The author admits the module is crazy, and he is awaiting a stable release of something new (Test2) to completely rewrite it in a sane way.
Still broken as of version: 0.32
Still broken in version: 0.052
Still broken as of version: 0.20
Still broken as of version: 0.11
Still broken as of version: 0.02
Still broken as of version: 0.11
use Test::Builder;
# A majority of tools out there do this:
# my $TB = Test::Builder->new;
# This works, but has always been wrong, forcing Test::Builder to implement
# subtests as a horrific hack. It also causes problems for tools that try
# to replace the singleton (also discouraged).
sub my_ok($;$) {
my ($bool, $name) = @_;
my $TB = Test::Builder->new;
$TB->ok($bool, $name);
}
sub my_diag($) {
my ($msg) = @_;
my $TB = Test::Builder->new;
$TB->diag($msg);
}
use Test2::API qw/context/;
sub my_ok($;$) {
my ($bool, $name) = @_;
my $ctx = context();
$ctx->ok($bool, $name);
$ctx->release;
}
sub my_diag($) {
my ($msg) = @_;
my $ctx = context();
$ctx->diag($msg);
$ctx->release;
}
The context object has API compatible implementations of the following methods:
diag(@messages)note(@messages)If you are looking for helpers with is, like, and others, see
the Test2::Suite manpage.
use Test::More;
sub exclusive_ok {
my ($bool1, $bool2, $name) = @_;
# Ensure errors are reported 1 level higher
local $Test::Builder::Level = $Test::Builder::Level + 1;
$ok = $bool1 || $bool2;
$ok &&= !($bool1 && $bool2);
ok($ok, $name);
return $bool;
}
Every single tool in the chain from this, to ok, to anything ok calls
needs to increment the $Level variable. When an error occurs Test::Builder
will do a trace to the stack frame determined by $Level, and report that
file+line as the one where the error occurred. If you or any other tool you use
forgets to set $Level then errors will be reported to the wrong place.
use Test::More;
sub exclusive_ok {
my ($bool1, $bool2, $name) = @_;
# Grab and store the context, even if you do not need to use it
# directly.
my $ctx = context();
$ok = $bool1 || $bool2;
$ok &&= !($bool1 && $bool2);
ok($ok, $name);
$ctx->release;
return $bool;
}
Instead of using $Level to perform a backtrace, Test2 uses a context
object. In this sample you create a context object and store it. This locks the
context (errors report 1 level up from here) for all wrapped tools to find. You
do not need to use the context object, but you do need to store it in a
variable. Once the sub ends the $ctx variable is destroyed which lets future
tools find their own.
# Set the mode BEFORE anything loads Test::Builder
use open ':std', ':encoding(utf8)';
use Test::More;
Or
# Modify the filehandles
my $builder = Test::More->builder;
binmode $builder->output, ":encoding(utf8)";
binmode $builder->failure_output, ":encoding(utf8)";
binmode $builder->todo_output, ":encoding(utf8)";
use Test2::API qw/test2_stack/;
test2_stack->top->format->encoding('utf8');
Though a much better way is to use the the Test2::Plugin::UTF8 manpage plugin, which is part of the Test2::Suite manpage.
The following people have all contributed to this document in some way, even if only for review.
The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.
Copyright 2019 Chad Granum <exodist@cpan.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
| Test2::Transition - Transition notes when upgrading to Test2 |