{
    "mode": "perldoc",
    "parameter": "Test::Tester",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Test%3A%3ATester/json",
    "generated": "2026-06-03T08:21:03Z",
    "synopsis": "use Test::Tester tests => 6;\nuse Test::MyStyle;\nchecktest(\nsub {\nismystyleeq(\"this\", \"that\", \"not eq\");\n},\n{\nok => 0, # expect this to fail\nname => \"not eq\",\ndiag => \"Expected: 'this'\\nGot: 'that'\",\n}\n);\nor\nuse Test::Tester tests => 6;\nuse Test::MyStyle;\nchecktest(\nsub {\nismystyleqr(\"this\", \"that\", \"not matching\");\n},\n{\nok => 0, # expect this to fail\nname => \"not matching\",\ndiag => qr/Expected: 'this'\\s+Got: 'that'/,\n}\n);\nor\nuse Test::Tester;\nuse Test::More tests => 3;\nuse Test::MyStyle;\nmy ($premature, @results) = runtests(\nsub {\nisdatabasealive(\"dbname\");\n}\n);\n# now use Test::More::like to check the diagnostic output\nlike($results[0]->{diag}, \"/^Database ping took \\\\d+ seconds$\"/, \"diag\");",
    "sections": {
        "NAME": {
            "content": "Test::Tester - Ease testing test modules built with Test::Builder\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Test::Tester tests => 6;\n\nuse Test::MyStyle;\n\nchecktest(\nsub {\nismystyleeq(\"this\", \"that\", \"not eq\");\n},\n{\nok => 0, # expect this to fail\nname => \"not eq\",\ndiag => \"Expected: 'this'\\nGot: 'that'\",\n}\n);\n\nor\n\nuse Test::Tester tests => 6;\n\nuse Test::MyStyle;\n\nchecktest(\nsub {\nismystyleqr(\"this\", \"that\", \"not matching\");\n},\n{\nok => 0, # expect this to fail\nname => \"not matching\",\ndiag => qr/Expected: 'this'\\s+Got: 'that'/,\n}\n);\n\nor\n\nuse Test::Tester;\n\nuse Test::More tests => 3;\nuse Test::MyStyle;\n\nmy ($premature, @results) = runtests(\nsub {\nisdatabasealive(\"dbname\");\n}\n);\n\n# now use Test::More::like to check the diagnostic output\n\nlike($results[0]->{diag}, \"/^Database ping took \\\\d+ seconds$\"/, \"diag\");\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "If you have written a test module based on Test::Builder then Test::Tester allows you to test it\nwith the minimum of effort.\n\nHOW TO USE (THE EASY WAY)\nFrom version 0.08 Test::Tester no longer requires you to included anything special in your test\nmodules. All you need to do is\n\nuse Test::Tester;\n\nin your test script before any other Test::Builder based modules and away you go.\n\nOther modules based on Test::Builder can be used to help with the testing. In fact you can even\nuse functions from your module to test other functions from the same module (while this is\npossible it is probably not a good idea, if your module has bugs, then using it to test itself\nmay give the wrong answers).\n\nThe easiest way to test is to do something like\n\nchecktest(\nsub { ismystyleeq(\"this\", \"that\", \"not eq\") },\n{\nok => 0, # we expect the test to fail\nname => \"not eq\",\ndiag => \"Expected: 'this'\\nGot: 'that'\",\n}\n);\n\nthis will execute the ismystyleeq test, capturing its results and checking that they are what\nwas expected.\n\nYou may need to examine the test results in a more flexible way, for example, the diagnostic\noutput may be quite long or complex or it may involve something that you cannot predict in\nadvance like a timestamp. In this case you can get direct access to the test results:\n\nmy ($premature, @results) = runtests(\nsub {\nisdatabasealive(\"dbname\");\n}\n);\n\nlike($result[0]->{diag}, \"/^Database ping took \\\\d+ seconds$\"/, \"diag\");\n\nor\n\nchecktest(\nsub { ismystyleqr(\"this\", \"that\", \"not matching\") },\n{\nok => 0, # we expect the test to fail\nname => \"not matching\",\ndiag => qr/Expected: 'this'\\s+Got: 'that'/,\n}\n);\n\nWe cannot predict how long the database ping will take so we use Test::More's like() test to\ncheck that the diagnostic string is of the right form.\n\nHOW TO USE (THE HARD WAY)\n*This is here for backwards compatibility only*\n\nMake your module use the Test::Tester::Capture object instead of the Test::Builder one. How to\ndo this depends on your module but assuming that your module holds the Test::Builder object in\n$Test and that all your test routines access it through $Test then providing a function\nsomething like this\n\nsub setbuilder\n{\n$Test = shift;\n}\n\nshould allow your test scripts to do\n\nTest::YourModule::setbuilder(Test::Tester->capture);\n\nand after that any tests inside your module will captured.\n",
            "subsections": []
        },
        "TEST RESULTS": {
            "content": "The result of each test is captured in a hash. These hashes are the same as the hashes returned\nby Test::Builder->details but with a couple of extra fields.\n\nThese fields are documented in Test::Builder in the details() function\n\nok\nDid the test pass?\n\nactualok\nDid the test really pass? That is, did the pass come from Test::Builder->ok() or did it pass\nbecause it was a TODO test?\n\nname\nThe name supplied for the test.\n\ntype\nWhat kind of test? Possibilities include, skip, todo etc. See Test::Builder for more details.\n\nreason\nThe reason for the skip, todo etc. See Test::Builder for more details.\n\nThese fields are exclusive to Test::Tester.\n\ndiag\nAny diagnostics that were output for the test. This only includes diagnostics output after the\ntest result is declared.\n\nNote that Test::Builder ensures that any diagnostics end in a \\n and it in earlier versions of\nTest::Tester it was essential that you have the final \\n in your expected diagnostics. From\nversion 0.10 onward, Test::Tester will add the \\n if you forgot it. It will not add a \\n if\nyou are expecting no diagnostics. See below for help tracking down hard to find space and tab\nrelated problems.\n\ndepth\nThis allows you to check that your test module is setting the correct value for\n$Test::Builder::Level and thus giving the correct file and line number when a test fails. It\nis calculated by looking at caller() and $Test::Builder::Level. It should count how many\nsubroutines there are before jumping into the function you are testing. So for example in\n\nruntests( sub { mytestfunction(\"a\", \"b\") } );\n\nthe depth should be 1 and in\n\nsub deeper { mytestfunction(\"a\", \"b\") }\n\nruntests(sub { deeper() });\n\ndepth should be 2, that is 1 for the sub {} and one for deeper(). This might seem a little\ncomplex but if your tests look like the simple examples in this doc then you don't need to\nworry as the depth will always be 1 and that's what Test::Tester expects by default.\n\nNote: if you do not specify a value for depth in checktest() then it automatically compares\nit against 1, if you really want to skip the depth test then pass in undef.\n\nNote: depth will not be correctly calculated for tests that run from a signal handler or an\nEND block or anywhere else that hides the call stack.\n\nSome of Test::Tester's functions return arrays of these hashes, just like\nTest::Builder->details. That is, the hash for the first test will be array element 1 (not 0).\nElement 0 will not be a hash it will be a string which contains any diagnostic output that came\nbefore the first test. This should usually be empty, if it's not, it means something output\ndiagnostics before any test results showed up.\n",
            "subsections": []
        },
        "SPACES AND TABS": {
            "content": "Appearances can be deceptive, especially when it comes to emptiness. If you are scratching your\nhead trying to work out why Test::Tester is saying that your diagnostics are wrong when they\nlook perfectly right then the answer is probably whitespace. From version 0.10 on, Test::Tester\nsurrounds the expected and got diag values with single quotes to make it easier to spot trailing\nwhitespace. So in this example\n\n# Got diag (5 bytes):\n# 'abcd '\n# Expected diag (4 bytes):\n# 'abcd'\n\nit is quite clear that there is a space at the end of the first string. Another way to solve\nthis problem is to use colour and inverse video on an ANSI terminal, see below COLOUR below if\nyou want this.\n\nUnfortunately this is sometimes not enough, neither colour nor quotes will help you with\nproblems involving tabs, other non-printing characters and certain kinds of problems inherent in\nUnicode. To deal with this, you can switch Test::Tester into a mode whereby all \"tricky\"\ncharacters are shown as \\{xx}. Tricky characters are those with ASCII code less than 33 or\nhigher than 126. This makes the output more difficult to read but much easier to find subtle\ndifferences between strings. To turn on this mode either call \"showspace()\" in your test script\nor set the \"TESTTESTERSPACE\" environment variable to be a true value. The example above would\nthen look like\n\n# Got diag (5 bytes):\n# abcd\\x{20}\n# Expected diag (4 bytes):\n# abcd\n",
            "subsections": []
        },
        "COLOUR": {
            "content": "If you prefer to use colour as a means of finding tricky whitespace characters then you can set\nthe \"TESTTESTCOLOUR\" environment variable to a comma separated pair of colours, the first for\nthe foreground, the second for the background. For example \"white,red\" will print white text on\na red background. This requires the Term::ANSIColor module. You can specify any colour that\nwould be acceptable to the Term::ANSIColor::color function.\n\nIf you spell colour differently, that's no problem. The \"TESTTESTERCOLOR\" variable also works\n(if both are set then the British spelling wins out).\n",
            "subsections": []
        },
        "EXPORTED FUNCTIONS": {
            "content": "($premature, @results) = runtests(\\&testsub)\n\\&testsub is a reference to a subroutine.\n\nruntests runs the subroutine in $testsub and captures the results of any tests inside it. You\ncan run more than 1 test inside this subroutine if you like.\n\n$premature is a string containing any diagnostic output from before the first test.\n\n@results is an array of test result hashes.\n\ncmpresult(\\%result, \\%expect, $name)\n\\%result is a ref to a test result hash.\n\n\\%expect is a ref to a hash of expected values for the test result.\n\ncmpresult compares the result with the expected values. If any differences are found it outputs\ndiagnostics. You may leave out any field from the expected result and cmpresult will not do the\ncomparison of that field.\n\ncmpresults(\\@results, \\@expects, $name)\n\\@results is a ref to an array of test results.\n\n\\@expects is a ref to an array of hash refs.\n\ncmpresults checks that the results match the expected results and if any differences are found\nit outputs diagnostics. It first checks that the number of elements in \\@results and \\@expects\nis the same. Then it goes through each result checking it against the expected result as in",
            "subsections": [
                {
                    "name": "cmp_result",
                    "content": "($premature, @results) = checktests(\\&testsub, \\@expects, $name)\n\\&testsub is a reference to a subroutine.\n\n\\@expect is a ref to an array of hash refs which are expected test results.\n\nchecktests combines runtests and cmptests into a single call. It also checks if the tests\ndied at any stage.\n\nIt returns the same values as runtests, so you can further examine the test results if you need\nto.\n\n($premature, @results) = checktest(\\&testsub, \\%expect, $name)\n\\&testsub is a reference to a subroutine.\n\n\\%expect is a ref to an hash of expected values for the test result.\n\nchecktest is a wrapper around checktests. It combines runtests and cmptests into a single\ncall, checking if the test died. It assumes that only a single test is run inside \\&testsub and\ninclude a test to make sure this is true.\n\nIt returns the same values as runtests, so you can further examine the test results if you need\nto.\n\nshowspace()\nTurn on the escaping of characters as described in the SPACES AND TABS section.\n"
                }
            ]
        },
        "HOW IT WORKS": {
            "content": "Normally, a test module (let's call it Test:MyStyle) calls Test::Builder->new to get the\nTest::Builder object. Test::MyStyle calls methods on this object to record information about\ntest results. When Test::Tester is loaded, it replaces Test::Builder's new() method with one\nwhich returns a Test::Tester::Delegate object. Most of the time this object behaves as the real\nTest::Builder object. Any methods that are called are delegated to the real Test::Builder object\nso everything works perfectly. However once we go into test mode, the method calls are no longer\npassed to the real Test::Builder object, instead they go to the Test::Tester::Capture object.\nThis object seems exactly like the real Test::Builder object, except, instead of outputting test\nresults and diagnostics, it just records all the information for later analysis.\n",
            "subsections": []
        },
        "CAVEATS": {
            "content": "Support for calling Test::Builder->note is minimal. It's implemented as an empty stub, so\nmodules that use it will not crash but the calls are not recorded for testing purposes like the\nothers. Patches welcome.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Test::Builder the source of testing goodness. Test::Builder::Tester for an alternative approach\nto the problem tackled by Test::Tester - captures the strings output by Test::Builder. This\nmeans you cannot get separate access to the individual pieces of information and you must\npredict exactly what your test will output.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts are based on other\npeople's work.\n\nPlan handling lifted from Test::More. written by Michael G Schwern <schwern@pobox.com>.\n\nTest::Tester::Capture is a cut down and hacked up version of Test::Builder. Test::Builder was\nwritten by chromatic <chromatic@wgz.org> and Michael G Schwern <schwern@pobox.com>.\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Under the same license as Perl itself\n\nSee http://www.perl.com/perl/misc/Artistic.html\n",
            "subsections": []
        }
    },
    "summary": "Test::Tester - Ease testing test modules built with Test::Builder",
    "flags": [],
    "examples": [],
    "see_also": []
}