{
    "mode": "perldoc",
    "parameter": "Test2::API::InterceptResult",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AAPI%3A%3AInterceptResult/json",
    "generated": "2026-06-03T13:59:23Z",
    "synopsis": "Usually you get an instance of this class when you use \"intercept()\" from Test2::API.\nuse Test2::V0;\nuse Test2::API qw/intercept/;\nmy $events = intercept {\nok(1, \"pass\");\nok(0, \"fail\");\ntodo \"broken\" => sub { ok(0, \"fixme\") };\nplan 3;\n};\n# This is typically the most useful construct\n# squashinfo() merges assertions and diagnostics that are associated\n#   (and returns a new instance with the modifications)\n# flatten() condenses the facet data into the key details for each event\n#   (and returns those structures in an arrayref)\nis(\n$events->squashinfo->flatten(),\n[\n{\ncausesfailure => 0,\nname => 'pass',\npass => 1,\ntracefile => 'xxx.t',\ntraceline => 5,\n},\n{\ncausesfailure => 1,\nname => 'fail',\npass => 0,\ntracefile => 'xxx.t',\ntraceline => 6,\n# There can be more than one diagnostics message so this is\n# always an array when present.\ndiag => [\"Failed test 'fail'\\nat xxx.t line 6.\"],\n},\n{\ncausesfailure => 0,\nname => 'fixme',\npass => 0,\ntracefile => 'xxx.t',\ntraceline => 7,\n# There can be more than one diagnostics message or todo\n# reason, so these are always an array when present.\ntodo => ['broken'],\n# Diag message was turned into a note since the assertion was\n# TODO\nnote => [\"Failed test 'fixme'\\nat xxx.t line 7.\"],\n},\n{\ncausesfailure => 0,\nplan => 3,\ntracefile => 'xxx.t',\ntraceline => 8,\n},\n],\n\"Flattened events look like we expect\"\n);\nSee Test2::API::InterceptResult::Event for a full description of what \"flatten()\" provides for\neach event.",
    "sections": {
        "NAME": {
            "content": "Test2::API::InterceptResult - Representation of a list of events.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This class represents a list of events, normally obtained using \"intercept()\" from Test2::API.\n\nThis class is intended for people who with to verify the results of test tools they write.\n\nThis class provides methods to normalize, summarize, or map the list of events. The output of\nthese operations makes verifying your testing tools and the events they generate significantly\neasier. In most cases this spares you from needing a deep understanding of the event/facet\nmodel.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Usually you get an instance of this class when you use \"intercept()\" from Test2::API.\n\nuse Test2::V0;\nuse Test2::API qw/intercept/;\n\nmy $events = intercept {\nok(1, \"pass\");\nok(0, \"fail\");\ntodo \"broken\" => sub { ok(0, \"fixme\") };\nplan 3;\n};\n\n# This is typically the most useful construct\n# squashinfo() merges assertions and diagnostics that are associated\n#   (and returns a new instance with the modifications)\n# flatten() condenses the facet data into the key details for each event\n#   (and returns those structures in an arrayref)\nis(\n$events->squashinfo->flatten(),\n[\n{\ncausesfailure => 0,\n\nname => 'pass',\npass => 1,\n\ntracefile => 'xxx.t',\ntraceline => 5,\n},\n{\ncausesfailure => 1,\n\nname => 'fail',\npass => 0,\n\ntracefile => 'xxx.t',\ntraceline => 6,\n\n# There can be more than one diagnostics message so this is\n# always an array when present.\ndiag => [\"Failed test 'fail'\\nat xxx.t line 6.\"],\n},\n{\ncausesfailure => 0,\n\nname => 'fixme',\npass => 0,\n\ntracefile => 'xxx.t',\ntraceline => 7,\n\n# There can be more than one diagnostics message or todo\n# reason, so these are always an array when present.\ntodo => ['broken'],\n\n# Diag message was turned into a note since the assertion was\n# TODO\nnote => [\"Failed test 'fixme'\\nat xxx.t line 7.\"],\n},\n{\ncausesfailure => 0,\n\nplan => 3,\n\ntracefile => 'xxx.t',\ntraceline => 8,\n},\n],\n\"Flattened events look like we expect\"\n);\n\nSee Test2::API::InterceptResult::Event for a full description of what \"flatten()\" provides for\neach event.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Please note that no methods modify the original instance unless asked to do so.\n\nCONSTRUCTION\n$events = Test2::API::InterceptResult->new(@EVENTS)\n$events = Test2::API::InterceptResult->newfromref(\\@EVENTS)\nThese create a new instance of Test2::API::InterceptResult from the given events.\n\nIn the first form a new blessed arrayref is returned. In the 'newfromref' form the\nreference you pass in is directly blessed.\n\nBoth of these will throw an exception if called in void context. This is mainly important\nfor the 'filtering' methods listed below which normally return a new instance, they throw an\nexception in such cases as it probably means someone meant to filter the original in place.\n\n$clone = $events->clone()\nMake a clone of the original events. Note that this is a deep copy, the entire structure is\nduplicated. This uses \"dclone\" from Storable to achieve the deep clone.\n\nNORMALIZATION\n@events = $events->eventlist\nThis returns all the events in list-form.\n\n$hub = $events->hub\nThis returns a new Test2::Hub instance that has processed all the events contained in the\ninstance. This gives you a simple way to inspect the state changes your events cause.\n\n$state = $events->state\nThis returns a summary of the state of a hub after processing all the events.\n\n{\ncount        => 2,      # Number of assertions made\nfailed       => 1,      # Number of test failures seen\nispassing   => 0,      # Boolean, true if the test would be passing\n# after the events are processed.\n\nplan         => 2,      # Plan, either a number, undef, 'SKIP', or 'NO PLAN'\nfollowsplan => 1,      # True if there is a plan and it was followed.\n# False if the plan and assertions did not\n# match, undef if no plan was present in the\n# event list.\n\nbailedout   => undef,  # undef unless there was a bail-out in the\n# events in which case this will be a string\n# explaining why there was a bailout, if no\n# reason was given this will simply be set to\n# true (1).\n\nskipreason  => undef,  # If there was a skipall this will give the\n# reason.\n}\n\n$new = $events->upgrade\n$events->upgrade(inplace => $BOOL)\nNote: This normally returns a new instance, leaving the original unchanged. If you call it\nin void context it will throw an exception. If you want to modify the original you must pass\nin the \"inplace => 1\" option. You may call this in void context when you ask to modify it\nin place. The in-place form returns the instance that was modified so you can chain methods.\n\nThis will create a clone of the list where all events have been converted into\nTest2::API::InterceptResult::Event instances. This is extremely helpful as\nTest2::API::InterceptResult::Event provide a much better interface for working with events.\nThis allows you to avoid thinking about legacy event types.\n\nThis also means your tests against the list are not fragile if the tool you are testing\nrandomly changes what type of events it generates (IE Changing from Test2::Event::Ok to\nTest2::Event::Pass, both make assertions and both will normalize to identical (or close\nenough) Test2::API::InterceptResult::Event instances.\n\nReally you almost always want this, the only reason it is not done automatically is to make\nsure the \"intercept()\" tool is backwards compatible.\n\n$new = $events->squashinfo\n$events->squashinfo(inplace => $BOOL)\nNote: This normally returns a new instance, leaving the original unchanged. If you call it\nin void context it will throw an exception. If you want to modify the original you must pass\nin the \"inplace => 1\" option. You may call this in void context when you ask to modify it\nin place. The in-place form returns the instance that was modified so you can chain methods.\n\nNote: All events in the new or modified instance will be converted to\nTest2::API::InterceptResult::Event instances. There is no way to avoid this, the squash\noperation requires the upgraded event class.\n\nTest::More and many other legacy tools would send notes, diags, and assertions as seperate\nevents. A subtest in Test::More would send a note with the subtest name, the subtest\nassertion, and finally a diagnostics event if the subtest failed. This method will normalize\nthings by squashing the note and diag into the same event as the subtest (This is different\nfrom putting them into the subtest, which is not what happens).\n\nFILTERING\nNote: These normally return new instances, leaving the originals unchanged. If you call them in\nvoid context they will throw exceptions. If you want to modify the originals you must pass in\nthe \"inplace => 1\" option. You may call these in void context when you ask to modify them in\nplace. The in-place forms return the instance that was modified so you can chain methods.\n\n%PARAMS\nThese all accept the same 2 optional parameters:\n\ninplace => $BOOL\nWhen true the method will modify the instance in place instead of returning a new instance.\n\nargs => \\@ARGS\nIf you wish to pass parameters into the event method being used for filtering, you may do so\nhere.\n\nMETHODS\n$events->grep($CALL, %PARAMS)\nThis is essentially:\n\nTest2::API::InterceptResult->new(\ngrep { $->$CALL( @{$PARAMS{args}} ) } $self->eventlist,\n);\n\nNote: that $CALL is called on an upgraded version of the event, though the events returned\nwill be the original ones, not the upgraded ones.\n\n$CALL may be either the name of a method on Test2::API::InterceptResult::Event, or a\ncoderef.\n\n$events->asserts(%PARAMS)\nThis is essentially:\n\n$events->grep(hasassert => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that made assertions.\n\n$events->subtests(%PARAMS)\nThis is essentially:\n\n$events->grep(hassubtest => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that have subtests.\n\n$events->diags(%PARAMS)\nThis is essentially:\n\n$events->grep(hasdiags => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that have diags.\n\n$events->notes(%PARAMS)\nThis is essentially:\n\n$events->grep(hasnotes => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that have notes.\n\n$events->errors(%PARAMS)\nNote: Errors are NOT failing assertions. Failing assertions are a different thing.\n\nThis is essentially:\n\n$events->grep(haserrors => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that have errors.\n\n$events->plans(%PARAMS)\nThis is essentially:\n\n$events->grep(hasplan => @{$PARAMS{args}})\n\nIt returns a new instance containing only the events that set the plan.\n\n$events->causesfail(%PARAMS)\n$events->causesfailure(%PARAMS)\nThese are essentially:\n\n$events->grep(causesfail    => @{$PARAMS{args}})\n$events->grep(causesfailure => @{$PARAMS{args}})\n\nNote: \"causesfail()\" and \"causesfailure()\" are both aliases for eachother in events, so\nthese methods are effectively aliases here as well.\n\nIt returns a new instance containing only the events that cause failure.\n\nMAPPING\nThese methods ALWAYS return an arrayref.\n\nNote: No methods on Test2::API::InterceptResult::Event alter the event in any way.\n\nImportant Notes about Events:\n\nTest2::API::InterceptResult::Event was tailor-made to be used in event-lists. Most methods that\nare not applicable to a given event will return an empty list, so you normally do not need to\nworry about unwanted \"undef\" values or exceptions being thrown. Mapping over event methods is an\nentended use, so it works well to produce lists.\n\nExceptions to the rule:\n\nSome methods such as \"causesfail\" always return a boolean true or false for all events. Any\nmethod prefixed with \"the\" conveys the intent that the event should have exactly 1 of\nsomething, so those will throw an exception when that condition is not true.\n\n$arrayref = $events->map($CALL, %PARAMS)\nThis is essentially:\n\n[ map { $->$CALL(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\n$CALL may be either the name of a method on Test2::API::InterceptResult::Event, or a\ncoderef.\n\n$arrayref = $events->flatten(%PARAMS)\nThis is essentially:\n\n[ map { $->flatten(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of flattened structures.\n\nSee Test2::API::InterceptResult::Event for details on what \"flatten()\" returns.\n\n$arrayref = $events->briefs(%PARAMS)\nThis is essentially:\n\n[ map { $->briefs(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of event briefs.\n\nSee Test2::API::InterceptResult::Event for details on what \"brief()\" returns.\n\n$arrayref = $events->summaries(%PARAMS)\nThis is essentially:\n\n[ map { $->summaries(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of event summaries.\n\nSee Test2::API::InterceptResult::Event for details on what \"summary()\" returns.\n\n$arrayref = $events->subtestresults(%PARAMS)\nThis is essentially:\n\n[ map { $->subtestresult(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of event summaries.\n\nSee Test2::API::InterceptResult::Event for details on what \"subtestresult()\" returns.\n\n$arrayref = $events->diagmessages(%PARAMS)\nThis is essentially:\n\n[ map { $->diagmessages(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of diagnostic messages (strings).\n\nSee Test2::API::InterceptResult::Event for details on what \"diagmessages()\" returns.\n\n$arrayref = $events->notemessages(%PARAMS)\nThis is essentially:\n\n[ map { $->notemessages(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of notification messages (strings).\n\nSee Test2::API::InterceptResult::Event for details on what \"notemessages()\" returns.\n\n$arrayref = $events->errormessages(%PARAMS)\nThis is essentially:\n\n[ map { $->errormessages(@{ $PARAMS{args} }) } $events->upgrade->eventlist ];\n\nIt returns a new list of error messages (strings).\n\nSee Test2::API::InterceptResult::Event for details on what \"errormessages()\" returns.\n",
            "subsections": []
        },
        "SOURCE": {
            "content": "The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.\n",
            "subsections": []
        },
        "MAINTAINERS": {
            "content": "Chad Granum <exodist@cpan.org>\n",
            "subsections": []
        },
        "AUTHORS": {
            "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://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Test2::API::InterceptResult - Representation of a list of events.",
    "flags": [],
    "examples": [],
    "see_also": []
}