diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Test2::Transition.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Test2::Transition.3pm | 530 |
1 files changed, 530 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test2::Transition.3pm b/upstream/mageia-cauldron/man3pm/Test2::Transition.3pm new file mode 100644 index 00000000..a2ec5a5a --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Test2::Transition.3pm @@ -0,0 +1,530 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test2::Transition 3pm" +.TH Test2::Transition 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test2::Transition \- Transition notes when upgrading to Test2 +.SH DESCRIPTION +.IX Header "DESCRIPTION" +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. +.SH "THINGS THAT BREAK" +.IX Header "THINGS THAT BREAK" +This is the list of scenarios that break with the new internals. +.SS "Test::Builder1.5/2 conditionals" +.IX Subsection "Test::Builder1.5/2 conditionals" +\fIThe Problem\fR +.IX Subsection "The Problem" +.PP +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. +.PP +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. +.PP +\fIThe Fix\fR +.IX Subsection "The Fix" +.PP +The fix is to remove all Test::Builder1.5/2 related code. Either use the +legacy Test::Builder API, or use Test2 directly. +.SS "Replacing the Test::Builder singleton" +.IX Subsection "Replacing the Test::Builder singleton" +\fIThe Problem\fR +.IX Subsection "The Problem" +.PP +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. +.PP +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. +.PP +\fIThe Fix\fR +.IX Subsection "The Fix" +.PP +If you simply want to intercept all results instead of letting them go to TAP, +you should look at the Test2::API docs and read about pushing a new hub onto +the hub stack. Replacing the hub temporarily is now the correct way to +intercept results. +.PP +If your goal is purely monitoring of events use the \f(CW\*(C`Test2::Hub\->listen()\*(C'\fR +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 \f(CW\*(C`Test2::Hub\->filter()\*(C'\fR +method. +.SS "Directly Accessing Hash Elements" +.IX Subsection "Directly Accessing Hash Elements" +\fIThe Problem\fR +.IX Subsection "The Problem" +.PP +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. +.PP +\fIThe Fix\fR +.IX Subsection "The Fix" +.PP +The fix is to use the API specified in Test2::API to look at or modify state +as needed. +.SS "Subtest indentation" +.IX Subsection "Subtest indentation" +\fIThe Problem\fR +.IX Subsection "The Problem" +.PP +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: +.PP +.Vb 4 +\& # subtest foo +\& ok 1 \- blah +\& 1..1 +\& ok 1 \- subtest foo +.Ve +.PP +The old style indented the note: +.PP +.Vb 4 +\& # subtest foo +\& ok 1 \- blah +\& 1..1 +\& ok 1 \- subtest foo +.Ve +.PP +This breaks tests that do string comparison of TAP output. +.PP +\fIThe Fix\fR +.IX Subsection "The Fix" +.PP +.Vb 1 +\& my $indent = $INC{\*(AqTest2/API.pm\*(Aq} ? \*(Aq\*(Aq : \*(Aq \*(Aq; +\& +\& is( +\& $subtest_output, +\& "${indent}# subtest foo", +\& "Got subtest note" +\& ); +.Ve +.PP +Check if \f(CW$INC{\*(AqTest2/API.pm\*(Aq}\fR is set, if it is then no indentation should be +expected. If it is not set, then the old Test::Builder is in use, indentation +should be expected. +.SH "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED" +.IX Header "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED" +This is a list of cpan modules that have been known to have been broken by the +upgrade at one point. +.SS "WORKS BUT TESTS WILL FAIL" +.IX Subsection "WORKS BUT TESTS WILL FAIL" +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. +.IP Test::DBIx::Class::Schema 4 +.IX Item "Test::DBIx::Class::Schema" +This module has a test that appears to work around a Test::Builder bug. The bug +appears to have been fixed by Test2, which means the workaround causes a +failure. This can be easily updated, but nobody has done so yet. +.Sp +Known broken in versions: 1.0.9 and older +.IP Device::Chip 4 +.IX Item "Device::Chip" +Tests break due to subtest indentation. +.Sp +Known broken in version 0.07. Apparently works fine in 0.06 though. Patch has +been submitted to fix the issue. +.SS "UPGRADE SUGGESTED" +.IX Subsection "UPGRADE SUGGESTED" +These are modules that did not break, but had broken test suites that have +since been fixed. +.IP Test::Exception 4 +.IX Item "Test::Exception" +Old versions work fine, but have a minor test name behavior that breaks with +Test2. Old versions will no longer install because of this. The latest version +on CPAN will install just fine. Upgrading is not required, but is recommended. +.Sp +Fixed in version: 0.43 +.IP Data::Peek 4 +.IX Item "Data::Peek" +Some tests depended on \f(CW$!\fR and \f(CW$?\fR being modified in subtle ways. A patch +was applied to correct things that changed. +.Sp +The module itself works fine, there is no need to upgrade. +.Sp +Fixed in version: 0.45 +.IP circular::require 4 +.IX Item "circular::require" +Some tests were fragile and required base.pm to be loaded at a late stage. +Test2 was loading base.pm too early. The tests were updated to fix this. +.Sp +The module itself never broke, you do not need to upgrade. +.Sp +Fixed in version: 0.12 +.IP Test::Module::Used 4 +.IX Item "Test::Module::Used" +A test worked around a now-fixed planning bug. There is no need to upgrade if +you have an old version installed. New versions install fine if you want them. +.Sp +Fixed in version: 0.2.5 +.IP Test::Moose::More 4 +.IX Item "Test::Moose::More" +Some tests were fragile, but have been fixed. The actual breakage was from the +subtest comment indentation change. +.Sp +No need to upgrade, old versions work fine. Only new versions will install. +.Sp +Fixed in version: 0.025 +.IP Test::FITesque 4 +.IX Item "Test::FITesque" +This was broken by a bugfix to how planning is done. The test was updated after +the bugfix. +.Sp +Fixed in version: 0.04 +.IP Test::Kit 4 +.IX Item "Test::Kit" +Old versions work fine, but would not install because Test::Aggregate was in +the dependency chain. An upgrade should not be needed. +.Sp +Fixed in version: 2.15 +.IP autouse 4 +.IX Item "autouse" +A test broke because it depended on Scalar::Util not being loaded. Test2 loads +Scalar::Util. The test was updated to load Test2 after checking Scalar::Util's +load status. +.Sp +There is no need to upgrade if you already have it installed. +.Sp +Fixed in version: 1.11 +.SS "NEED TO UPGRADE" +.IX Subsection "NEED TO UPGRADE" +.IP Test::SharedFork 4 +.IX Item "Test::SharedFork" +Old versions need to directly access Test::Builder singleton hash elements. The +latest version on CPAN will still do this on old Test::Builder, but will defer +to Test2::IPC on Test2. +.Sp +Fixed in version: 0.35 +.IP Test::Builder::Clutch 4 +.IX Item "Test::Builder::Clutch" +This works by doing overriding methods on the singleton, and directly accessing +hash values on the singleton. A new version has been released that uses the +Test2 API to accomplish the same result in a saner way. +.Sp +Fixed in version: 0.07 +.IP Test::Dist::VersionSync 4 +.IX Item "Test::Dist::VersionSync" +This had Test::Builder2 conditionals. This was fixed by removing the +conditionals. +.Sp +Fixed in version: 1.1.4 +.IP Test::Modern 4 +.IX Item "Test::Modern" +This relied on \f(CW\*(C`Test::Builder\->_try()\*(C'\fR which was a private method, +documented as something nobody should use. This was fixed by using a different +tool. +.Sp +Fixed in version: 0.012 +.IP Test::UseAllModules 4 +.IX Item "Test::UseAllModules" +Version 0.14 relied on \f(CW\*(C`Test::Builder\->history\*(C'\fR which was available in +Test::Builder 1.5. Versions 0.12 and 0.13 relied on other Test::Builder +internals. +.Sp +Fixed in version: 0.15 +.IP Test::More::Prefix 4 +.IX Item "Test::More::Prefix" +Worked by applying a role that wrapped \f(CW\*(C`Test::Builder\->_print_comment\*(C'\fR. +Fixed by adding an event filter that modifies the message instead when running +under Test2. +.Sp +Fixed in version: 0.007 +.SS "STILL BROKEN" +.IX Subsection "STILL BROKEN" +.IP Test::Aggregate 4 +.IX Item "Test::Aggregate" +This distribution directly accesses the hash keys in the Test::Builder +singleton. It also approaches the problem from the wrong angle, please consider +using Test2::Aggregate for similar functionality and Test2::Harness +which allows module preloading at the harness level. +.Sp +Still broken as of version: 0.373 +.IP Test::Wrapper 4 +.IX Item "Test::Wrapper" +This module directly uses hash keys in the Test::Builder singleton. This +module is also obsolete thanks to the benefits of Test2. Use \f(CWintercept()\fR +from Test2::API to achieve a similar result. +.Sp +Still broken as of version: 0.3.0 +.IP Test::ParallelSubtest 4 +.IX Item "Test::ParallelSubtest" +This module overrides \f(CWTest::Builder::subtest()\fR and +\&\f(CWTest::Builder::done_testing()\fR. It also directly accesses hash elements of +the singleton. It has not yet been fixed. +.Sp +Alternatives: Test2::AsyncSubtest and Test2::Workflow (not stable). +.Sp +Still broken as of version: 0.05 +.IP Test::Pretty 4 +.IX Item "Test::Pretty" +See https://github.com/tokuhirom/Test\-Pretty/issues/25 +.Sp +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. +.Sp +Still broken as of version: 0.32 +.IP Net::BitTorrent 4 +.IX Item "Net::BitTorrent" +The tests for this module directly access Test::Builder hash keys. Most, if +not all of these hash keys have public API methods that could be used instead +to avoid the problem. +.Sp +Still broken in version: 0.052 +.IP Test::Group 4 +.IX Item "Test::Group" +It monkeypatches Test::Builder, and calls it "black magic" in the code. +.Sp +Still broken as of version: 0.20 +.IP Test::Flatten 4 +.IX Item "Test::Flatten" +This modifies the Test::Builder internals in many ways. A better was to +accomplish the goal of this module is to write your own subtest function. +.Sp +Still broken as of version: 0.11 +.IP Log::Dispatch::Config::TestLog 4 +.IX Item "Log::Dispatch::Config::TestLog" +Modifies Test::Builder internals. +.Sp +Still broken as of version: 0.02 +.IP Test::Able 4 +.IX Item "Test::Able" +Modifies Test::Builder internals. +.Sp +Still broken as of version: 0.11 +.SH "MAKE ASSERTIONS \-> SEND EVENTS" +.IX Header "MAKE ASSERTIONS -> SEND EVENTS" +.SS LEGACY +.IX Subsection "LEGACY" +.Vb 1 +\& 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); +\& } +.Ve +.SS TEST2 +.IX Subsection "TEST2" +.Vb 1 +\& 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; +\& } +.Ve +.PP +The context object has API compatible implementations of the following methods: +.ie n .IP "ok($bool, $name)" 4 +.el .IP "ok($bool, \f(CW$name\fR)" 4 +.IX Item "ok($bool, $name)" +.PD 0 +.IP diag(@messages) 4 +.IX Item "diag(@messages)" +.IP note(@messages) 4 +.IX Item "note(@messages)" +.ie n .IP "subtest($name, $code)" 4 +.el .IP "subtest($name, \f(CW$code\fR)" 4 +.IX Item "subtest($name, $code)" +.PD +.PP +If you are looking for helpers with \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`like\*(C'\fR, and others, see +Test2::Suite. +.SH "WRAP EXISTING TOOLS" +.IX Header "WRAP EXISTING TOOLS" +.SS LEGACY +.IX Subsection "LEGACY" +.Vb 1 +\& 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; +\& } +.Ve +.PP +Every single tool in the chain from this, to \f(CW\*(C`ok\*(C'\fR, to anything \f(CW\*(C`ok\*(C'\fR calls +needs to increment the \f(CW$Level\fR variable. When an error occurs Test::Builder +will do a trace to the stack frame determined by \f(CW$Level\fR, and report that +file+line as the one where the error occurred. If you or any other tool you use +forgets to set \f(CW$Level\fR then errors will be reported to the wrong place. +.SS TEST2 +.IX Subsection "TEST2" +.Vb 1 +\& 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; +\& } +.Ve +.PP +Instead of using \f(CW$Level\fR 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 \f(CW$ctx\fR variable is destroyed which lets future +tools find their own. +.SH "USING UTF8" +.IX Header "USING UTF8" +.SS LEGACY +.IX Subsection "LEGACY" +.Vb 3 +\& # Set the mode BEFORE anything loads Test::Builder +\& use open \*(Aq:std\*(Aq, \*(Aq:encoding(utf8)\*(Aq; +\& use Test::More; +.Ve +.PP +Or +.PP +.Vb 5 +\& # 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)"; +.Ve +.SS TEST2 +.IX Subsection "TEST2" +.Vb 1 +\& use Test2::API qw/test2_stack/; +\& +\& test2_stack\->top\->format\->encoding(\*(Aqutf8\*(Aq); +.Ve +.PP +Though a much better way is to use the Test2::Plugin::UTF8 plugin, which is +part of Test2::Suite. +.SH "AUTHORS, CONTRIBUTORS AND REVIEWERS" +.IX Header "AUTHORS, CONTRIBUTORS AND REVIEWERS" +The following people have all contributed to this document in some way, even if +only for review. +.IP "Chad Granum (EXODIST) <exodist@cpan.org>" 4 +.IX Item "Chad Granum (EXODIST) <exodist@cpan.org>" +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Test2 can be found at +\&\fIhttp://github.com/Test\-More/test\-more/\fR. +.SH MAINTAINER +.IX Header "MAINTAINER" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 Chad Granum <exodist@cpan.org>. +.PP +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR |