{
    "content": [
        {
            "type": "text",
            "text": "# Test2::Transition (perldoc)\n\n## NAME\n\nTest2::Transition - Transition notes when upgrading to Test2\n\n## DESCRIPTION\n\nThis is where gotchas and breakages related to the Test2 upgrade are documented. The upgrade\ncauses Test::Builder to defer to Test2 under the hood. This transition is mostly transparent,\nbut there are a few cases that can trip you up.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **THINGS THAT BREAK** (3 subsections)\n- **DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED** (4 subsections)\n- **WRAP EXISTING TOOLS**\n- **USING UTF8**\n- **SOURCE**\n- **MAINTAINER**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Test2::Transition",
        "section": "",
        "mode": "perldoc",
        "summary": "Test2::Transition - Transition notes when upgrading to Test2",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "THINGS THAT BREAK",
                "lines": 15,
                "subsections": [
                    {
                        "name": "Replacing the Test::Builder singleton",
                        "lines": 18
                    },
                    {
                        "name": "Directly Accessing Hash Elements",
                        "lines": 7
                    },
                    {
                        "name": "Subtest indentation",
                        "lines": 31
                    }
                ]
            },
            {
                "name": "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED",
                "lines": 218,
                "subsections": [
                    {
                        "name": "ok",
                        "lines": 1
                    },
                    {
                        "name": "diag",
                        "lines": 1
                    },
                    {
                        "name": "note",
                        "lines": 1
                    },
                    {
                        "name": "subtest",
                        "lines": 2
                    }
                ]
            },
            {
                "name": "WRAP EXISTING TOOLS",
                "lines": 45,
                "subsections": []
            },
            {
                "name": "USING UTF8",
                "lines": 26,
                "subsections": []
            },
            {
                "name": "SOURCE",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "MAINTAINER",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Test2::Transition - Transition notes when upgrading to Test2\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This is where gotchas and breakages related to the Test2 upgrade are documented. The upgrade\ncauses Test::Builder to defer to Test2 under the hood. This transition is mostly transparent,\nbut there are a few cases that can trip you up.\n",
                "subsections": []
            },
            "THINGS THAT BREAK": {
                "content": "This is the list of scenarios that break with the new internals.\n\nTest::Builder1.5/2 conditionals\nThe Problem\na few years back there were two attempts to upgrade/replace Test::Builder. Confusingly these\nwere called Test::Builder2 and Test::Builder1.5, in that order. Many people put conditionals in\ntheir code to check the Test::Builder version number and adapt their code accordingly.\n\nThe Test::Builder2/1.5 projects both died out. Now the conditional code people added has become\na mine field. A vast majority of modules broken by Test2 fall into this category.\n\nThe Fix\nThe fix is to remove all Test::Builder1.5/2 related code. Either use the legacy Test::Builder\nAPI, or use Test2 directly.\n",
                "subsections": [
                    {
                        "name": "Replacing the Test::Builder singleton",
                        "content": "The Problem\nSome test modules would replace the Test::Builder singleton instance with their own instance or\nsubclass. This was usually done to intercept or modify results as they happened.\n\nThe Test::Builder singleton is now a simple compatibility wrapper around Test2. The\nTest::Builder singleton is no longer the central place for results. Many results bypass the\nTest::Builder singleton completely, which breaks and behavior intended when replacing the\nsingleton.\n\nThe Fix\nIf you simply want to intercept all results instead of letting them go to TAP, you should look\nat the Test2::API docs and read about pushing a new hub onto the hub stack. Replacing the hub\ntemporarily is now the correct way to intercept results.\n\nIf your goal is purely monitoring of events use the \"Test2::Hub->listen()\" method exported by\nTest::More to watch events as they are fired. If you wish to modify results before they go to\nTAP look at the \"Test2::Hub->filter()\" method.\n"
                    },
                    {
                        "name": "Directly Accessing Hash Elements",
                        "content": "The Problem\nSome modules look directly at hash keys on the Test::Builder singleton. The problem here is that\nthe Test::Builder singleton no longer holds anything important.\n\nThe Fix\nThe fix is to use the API specified in Test2::API to look at or modify state as needed.\n"
                    },
                    {
                        "name": "Subtest indentation",
                        "content": "The Problem\nAn early change, in fact the change that made Test2 an idea, was a change to the indentation of\nthe subtest note. It was decided it would be more readable to outdent the subtest note instead\nof having it inline with the subtest:\n\n# subtest foo\nok 1 - blah\n1..1\nok 1 - subtest foo\n\nThe old style indented the note:\n\n# subtest foo\nok 1 - blah\n1..1\nok 1 - subtest foo\n\nThis breaks tests that do string comparison of TAP output.\n\nThe Fix\nmy $indent = $INC{'Test2/API.pm'} ? '' : '    ';\n\nis(\n$subtestoutput,\n\"${indent}# subtest foo\",\n\"Got subtest note\"\n);\n\nCheck if $INC{'Test2/API.pm'} is set, if it is then no indentation should be expected. If it is\nnot set, then the old Test::Builder is in use, indentation should be expected.\n"
                    }
                ]
            },
            "DISTRIBUTIONS THAT BREAK OR NEED TO BE UPGRADED": {
                "content": "This is a list of cpan modules that have been known to have been broken by the upgrade at one\npoint.\n\nWORKS BUT TESTS WILL FAIL\nThese modules still function correctly, but their test suites will not pass. If you already have\nthese modules installed then you can continue to use them. If you are trying to install them\nafter upgrading Test::Builder you will need to force installation, or bypass the broken tests.\n\nTest::DBIx::Class::Schema\nThis module has a test that appears to work around a Test::Builder bug. The bug appears to\nhave been fixed by Test2, which means the workaround causes a failure. This can be easily\nupdated, but nobody has done so yet.\n\nKnown broken in versions: 1.0.9 and older\n\nDevice::Chip\nTests break due to subtest indentation.\n\nKnown broken in version 0.07. Apparently works fine in 0.06 though. Patch has been submitted\nto fix the issue.\n\nUPGRADE SUGGESTED\nThese are modules that did not break, but had broken test suites that have since been fixed.\n\nTest::Exception\nOld versions work fine, but have a minor test name behavior that breaks with Test2. Old\nversions will no longer install because of this. The latest version on CPAN will install\njust fine. Upgrading is not required, but is recommended.\n\nFixed in version: 0.43\n\nData::Peek\nSome tests depended on $! and $? being modified in subtle ways. A patch was applied to\ncorrect things that changed.\n\nThe module itself works fine, there is no need to upgrade.\n\nFixed in version: 0.45\n\ncircular::require\nSome tests were fragile and required base.pm to be loaded at a late stage. Test2 was loading\nbase.pm too early. The tests were updated to fix this.\n\nThe module itself never broke, you do not need to upgrade.\n\nFixed in version: 0.12\n\nTest::Module::Used\nA test worked around a now-fixed planning bug. There is no need to upgrade if you have an\nold version installed. New versions install fine if you want them.\n\nFixed in version: 0.2.5\n\nTest::Moose::More\nSome tests were fragile, but have been fixed. The actual breakage was from the subtest\ncomment indentation change.\n\nNo need to upgrade, old versions work fine. Only new versions will install.\n\nFixed in version: 0.025\n\nTest::FITesque\nThis was broken by a bugfix to how planning is done. The test was updated after the bugfix.\n\nFixed in version: 0.04\n\nTest::Kit\nOld versions work fine, but would not install because Test::Aggregate was in the dependency\nchain. An upgrade should not be needed.\n\nFixed in version: 2.15\n\nautouse\nA test broke because it depended on Scalar::Util not being loaded. Test2 loads Scalar::Util.\nThe test was updated to load Test2 after checking Scalar::Util's load status.\n\nThere is no need to upgrade if you already have it installed.\n\nFixed in version: 1.11\n\nNEED TO UPGRADE\nTest::SharedFork\nOld versions need to directly access Test::Builder singleton hash elements. The latest\nversion on CPAN will still do this on old Test::Builder, but will defer to Test2::IPC on\nTest2.\n\nFixed in version: 0.35\n\nTest::Builder::Clutch\nThis works by doing overriding methods on the singleton, and directly accessing hash values\non the singleton. A new version has been released that uses the Test2 API to accomplish the\nsame result in a saner way.\n\nFixed in version: 0.07\n\nTest::Dist::VersionSync\nThis had Test::Builder2 conditionals. This was fixed by removing the conditionals.\n\nFixed in version: 1.1.4\n\nTest::Modern\nThis relied on \"Test::Builder->try()\" which was a private method, documented as something\nnobody should use. This was fixed by using a different tool.\n\nFixed in version: 0.012\n\nTest::UseAllModules\nVersion 0.14 relied on \"Test::Builder->history\" which was available in Test::Builder 1.5.\nVersions 0.12 and 0.13 relied on other Test::Builder internals.\n\nFixed in version: 0.15\n\nTest::More::Prefix\nWorked by applying a role that wrapped \"Test::Builder->printcomment\". Fixed by adding an\nevent filter that modifies the message instead when running under Test2.\n\nFixed in version: 0.007\n\nSTILL BROKEN\nTest::Aggregate\nThis distribution directly accesses the hash keys in the Test::Builder singleton. It also\napproaches the problem from the wrong angle, please consider using Test2::Aggregate for\nsimilar functionality and Test2::Harness which allows module preloading at the harness\nlevel.\n\nStill broken as of version: 0.373\n\nTest::Wrapper\nThis module directly uses hash keys in the Test::Builder singleton. This module is also\nobsolete thanks to the benefits of Test2. Use \"intercept()\" from Test2::API to achieve a\nsimilar result.\n\nStill broken as of version: 0.3.0\n\nTest::ParallelSubtest\nThis module overrides \"Test::Builder::subtest()\" and \"Test::Builder::donetesting()\". It\nalso directly accesses hash elements of the singleton. It has not yet been fixed.\n\nAlternatives: Test2::AsyncSubtest and Test2::Workflow (not stable).\n\nStill broken as of version: 0.05\n\nTest::Pretty\nSee https://github.com/tokuhirom/Test-Pretty/issues/25\n\nThe author admits the module is crazy, and he is awaiting a stable release of something new\n(Test2) to completely rewrite it in a sane way.\n\nStill broken as of version: 0.32\n\nNet::BitTorrent\nThe tests for this module directly access Test::Builder hash keys. Most, if not all of these\nhash keys have public API methods that could be used instead to avoid the problem.\n\nStill broken in version: 0.052\n\nTest::Group\nIt monkeypatches Test::Builder, and calls it \"black magic\" in the code.\n\nStill broken as of version: 0.20\n\nTest::Flatten\nThis modifies the Test::Builder internals in many ways. A better was to accomplish the goal\nof this module is to write your own subtest function.\n\nStill broken as of version: 0.11\n\nLog::Dispatch::Config::TestLog\nModifies Test::Builder internals.\n\nStill broken as of version: 0.02\n\nTest::Able\nModifies Test::Builder internals.\n\nStill broken as of version: 0.11\n\nMAKE ASSERTIONS -> SEND EVENTS\nLEGACY\nuse Test::Builder;\n\n# A majority of tools out there do this:\n# my $TB = Test::Builder->new;\n# This works, but has always been wrong, forcing Test::Builder to implement\n# subtests as a horrific hack. It also causes problems for tools that try\n# to replace the singleton (also discouraged).\n\nsub myok($;$) {\nmy ($bool, $name) = @;\nmy $TB = Test::Builder->new;\n$TB->ok($bool, $name);\n}\n\nsub mydiag($) {\nmy ($msg) = @;\nmy $TB = Test::Builder->new;\n$TB->diag($msg);\n}\n\nTEST2\nuse Test2::API qw/context/;\n\nsub myok($;$) {\nmy ($bool, $name) = @;\nmy $ctx = context();\n$ctx->ok($bool, $name);\n$ctx->release;\n}\n\nsub mydiag($) {\nmy ($msg) = @;\nmy $ctx = context();\n$ctx->diag($msg);\n$ctx->release;\n}\n\nThe context object has API compatible implementations of the following methods:\n",
                "subsections": [
                    {
                        "name": "ok",
                        "content": ""
                    },
                    {
                        "name": "diag",
                        "content": ""
                    },
                    {
                        "name": "note",
                        "content": ""
                    },
                    {
                        "name": "subtest",
                        "content": "If you are looking for helpers with \"is\", \"like\", and others, see Test2::Suite.\n"
                    }
                ]
            },
            "WRAP EXISTING TOOLS": {
                "content": "LEGACY\nuse Test::More;\n\nsub exclusiveok {\nmy ($bool1, $bool2, $name) = @;\n\n# Ensure errors are reported 1 level higher\nlocal $Test::Builder::Level = $Test::Builder::Level + 1;\n\n$ok = $bool1 || $bool2;\n$ok &&= !($bool1 && $bool2);\nok($ok, $name);\n\nreturn $bool;\n}\n\nEvery single tool in the chain from this, to \"ok\", to anything \"ok\" calls needs to increment the\n$Level variable. When an error occurs Test::Builder will do a trace to the stack frame\ndetermined by $Level, and report that file+line as the one where the error occurred. If you or\nany other tool you use forgets to set $Level then errors will be reported to the wrong place.\n\nTEST2\nuse Test::More;\n\nsub exclusiveok {\nmy ($bool1, $bool2, $name) = @;\n\n# Grab and store the context, even if you do not need to use it\n# directly.\nmy $ctx = context();\n\n$ok = $bool1 || $bool2;\n$ok &&= !($bool1 && $bool2);\nok($ok, $name);\n\n$ctx->release;\nreturn $bool;\n}\n\nInstead of using $Level to perform a backtrace, Test2 uses a context object. In this sample you\ncreate a context object and store it. This locks the context (errors report 1 level up from\nhere) for all wrapped tools to find. You do not need to use the context object, but you do need\nto store it in a variable. Once the sub ends the $ctx variable is destroyed which lets future\ntools find their own.\n",
                "subsections": []
            },
            "USING UTF8": {
                "content": "LEGACY\n# Set the mode BEFORE anything loads Test::Builder\nuse open ':std', ':encoding(utf8)';\nuse Test::More;\n\nOr\n\n# Modify the filehandles\nmy $builder = Test::More->builder;\nbinmode $builder->output,         \":encoding(utf8)\";\nbinmode $builder->failureoutput, \":encoding(utf8)\";\nbinmode $builder->todooutput,    \":encoding(utf8)\";\n\nTEST2\nuse Test2::API qw/test2stack/;\n\ntest2stack->top->format->encoding('utf8');\n\nThough a much better way is to use the Test2::Plugin::UTF8 plugin, which is part of\nTest2::Suite.\n\nAUTHORS, CONTRIBUTORS AND REVIEWERS\nThe following people have all contributed to this document in some way, even if only for review.\n\nChad Granum (EXODIST) <exodist@cpan.org>\n",
                "subsections": []
            },
            "SOURCE": {
                "content": "The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.\n",
                "subsections": []
            },
            "MAINTAINER": {
                "content": "Chad Granum <exodist@cpan.org>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright 2020 Chad Granum <exodist@cpan.org>.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee http://www.perl.com/perl/misc/Artistic.html\n",
                "subsections": []
            }
        }
    }
}