{ "content": [ { "type": "text", "text": "# Test2::API (perldoc)\n\n## NAME\n\nTest2::API - Primary interface for writing Test2 based testing tools. *INTERNALS NOTE* The internals of this package are subject to change at any time! The public methods provided will not change in backwards-incompatible ways (once there is a stable release), but the underlying implementation details might. Do not break encapsulation here! Currently the implementation is to create a single instance of the Test2::API::Instance Object. All class methods defer to the single instance. There is no public access to the singleton, and that is intentional. The class methods provided by this package provide the only functionality publicly exposed. This is done primarily to avoid the problems Test::Builder had by exposing its singleton. We do not want anyone to replace this singleton, rebless it, or directly muck with its internals. If you need to do something and cannot because of the restrictions placed here, then please report it as an issue. If possible, we will create a way for you to implement your functionality without exposing things that should not be exposed.\n\n## SYNOPSIS\n\nWRITING A TOOL\nThe \"context()\" method is your primary interface into the Test2 framework.\npackage My::Ok;\nuse Test2::API qw/context/;\nour @EXPORT = qw/myok/;\nuse base 'Exporter';\n# Just like ok() from Test::More\nsub myok($;$) {\nmy ($bool, $name) = @;\nmy $ctx = context(); # Get a context\n$ctx->ok($bool, $name);\n$ctx->release; # Release the context\nreturn $bool;\n}\nSee Test2::API::Context for a list of methods available on the context object.\nTESTING YOUR TOOLS\nThe \"intercept { ... }\" tool lets you temporarily intercept all events generated by the test\nsystem:\nuse Test2::API qw/intercept/;\nuse My::Ok qw/myok/;\nmy $events = intercept {\n# These events are not displayed\nmyok(1, \"pass\");\nmyok(0, \"fail\");\n};\nAs of version 1.302178 this now returns an arrayref that is also an instance of\nTest2::API::InterceptResult. See the Test2::API::InterceptResult documentation for details on\nhow to best use it.\nOTHER API FUNCTIONS\nuse Test2::API qw{\ntest2initdone\ntest2stack\ntest2setisend\ntest2getisend\ntest2ipc\ntest2formatterset\ntest2formatter\ntest2istestingdone\n};\nmy $init = test2initdone();\nmy $stack = test2stack();\nmy $ipc = test2ipc();\ntest2formatterset($FORMATTER)\nmy $formatter = test2formatter();\n... And others ...\n\n## DESCRIPTION\n\nThis package exports all the functions necessary to write and/or verify testing tools. Using\nthese building blocks you can begin writing test tools very quickly. You are also provided with\ntools that help you to test the tools you write.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **SYNOPSIS**\n- **MAIN API EXPORTS**\n- **OTHER API EXPORTS** (22 subsections)\n- **OTHER EXAMPLES**\n- **SEE ALSO**\n- **MAGIC**\n- **SOURCE**\n- **MAINTAINERS**\n- **AUTHORS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Test2::API", "section": "", "mode": "perldoc", "summary": "Test2::API - Primary interface for writing Test2 based testing tools. *INTERNALS NOTE* The internals of this package are subject to change at any time! The public methods provided will not change in backwards-incompatible ways (once there is a stable release), but the underlying implementation details might. Do not break encapsulation here! Currently the implementation is to create a single instance of the Test2::API::Instance Object. All class methods defer to the single instance. There is no public access to the singleton, and that is intentional. The class methods provided by this package provide the only functionality publicly exposed. This is done primarily to avoid the problems Test::Builder had by exposing its singleton. We do not want anyone to replace this singleton, rebless it, or directly muck with its internals. If you need to do something and cannot because of the restrictions placed here, then please report it as an issue. If possible, we will create a way for you to implement your functionality without exposing things that should not be exposed.", "synopsis": "WRITING A TOOL\nThe \"context()\" method is your primary interface into the Test2 framework.\npackage My::Ok;\nuse Test2::API qw/context/;\nour @EXPORT = qw/myok/;\nuse base 'Exporter';\n# Just like ok() from Test::More\nsub myok($;$) {\nmy ($bool, $name) = @;\nmy $ctx = context(); # Get a context\n$ctx->ok($bool, $name);\n$ctx->release; # Release the context\nreturn $bool;\n}\nSee Test2::API::Context for a list of methods available on the context object.\nTESTING YOUR TOOLS\nThe \"intercept { ... }\" tool lets you temporarily intercept all events generated by the test\nsystem:\nuse Test2::API qw/intercept/;\nuse My::Ok qw/myok/;\nmy $events = intercept {\n# These events are not displayed\nmyok(1, \"pass\");\nmyok(0, \"fail\");\n};\nAs of version 1.302178 this now returns an arrayref that is also an instance of\nTest2::API::InterceptResult. See the Test2::API::InterceptResult documentation for details on\nhow to best use it.\nOTHER API FUNCTIONS\nuse Test2::API qw{\ntest2initdone\ntest2stack\ntest2setisend\ntest2getisend\ntest2ipc\ntest2formatterset\ntest2formatter\ntest2istestingdone\n};\nmy $init = test2initdone();\nmy $stack = test2stack();\nmy $ipc = test2ipc();\ntest2formatterset($FORMATTER)\nmy $formatter = test2formatter();\n... And others ...", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 18, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [] }, { "name": "SYNOPSIS", "lines": 59, "subsections": [] }, { "name": "MAIN API EXPORTS", "lines": 305, "subsections": [] }, { "name": "OTHER API EXPORTS", "lines": 22, "subsections": [ { "name": "test2_set_is_end", "lines": 1 }, { "name": "test2_set_is_end", "lines": 38 }, { "name": "test2_ipc_wait_enable", "lines": 1 }, { "name": "test2_ipc_wait_disable", "lines": 8 }, { "name": "test2_no_wait", "lines": 15 }, { "name": "test2_reset_io", "lines": 9 }, { "name": "test2_add_callback_exit", "lines": 15 }, { "name": "test2_add_callback_post_load", "lines": 4 }, { "name": "test2_add_callback_testing_done", "lines": 14 }, { "name": "test2_add_callback_context_acquire", "lines": 14 }, { "name": "test2_add_callback_context_init", "lines": 3 }, { "name": "test2_add_callback_context_release", "lines": 3 }, { "name": "test2_add_callback_pre_subtest", "lines": 21 }, { "name": "test2_add_uuid_via", "lines": 21 }, { "name": "test2_ipc_add_driver", "lines": 8 }, { "name": "test2_ipc_enable_polling", "lines": 3 }, { "name": "test2_ipc_disable_polling", "lines": 2 }, { "name": "test2_ipc_enable_shm", "lines": 2 }, { "name": "test2_ipc_set_pending", "lines": 15 }, { "name": "test2_ipc_set_timeout", "lines": 23 }, { "name": "test2_formatter_set", "lines": 6 }, { "name": "test2_formatter_add", "lines": 3 } ] }, { "name": "OTHER EXAMPLES", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 11, "subsections": [] }, { "name": "MAGIC", "lines": 3, "subsections": [] }, { "name": "SOURCE", "lines": 2, "subsections": [] }, { "name": "MAINTAINERS", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "Test2::API - Primary interface for writing Test2 based testing tools.\n\n*INTERNALS NOTE*\nThe internals of this package are subject to change at any time! The public methods provided\nwill not change in backwards-incompatible ways (once there is a stable release), but the\nunderlying implementation details might. Do not break encapsulation here!\n\nCurrently the implementation is to create a single instance of the Test2::API::Instance Object.\nAll class methods defer to the single instance. There is no public access to the singleton, and\nthat is intentional. The class methods provided by this package provide the only functionality\npublicly exposed.\n\nThis is done primarily to avoid the problems Test::Builder had by exposing its singleton. We do\nnot want anyone to replace this singleton, rebless it, or directly muck with its internals. If\nyou need to do something and cannot because of the restrictions placed here, then please report\nit as an issue. If possible, we will create a way for you to implement your functionality\nwithout exposing things that should not be exposed.\n", "subsections": [] }, "DESCRIPTION": { "content": "This package exports all the functions necessary to write and/or verify testing tools. Using\nthese building blocks you can begin writing test tools very quickly. You are also provided with\ntools that help you to test the tools you write.\n", "subsections": [] }, "SYNOPSIS": { "content": "WRITING A TOOL\nThe \"context()\" method is your primary interface into the Test2 framework.\n\npackage My::Ok;\nuse Test2::API qw/context/;\n\nour @EXPORT = qw/myok/;\nuse base 'Exporter';\n\n# Just like ok() from Test::More\nsub myok($;$) {\nmy ($bool, $name) = @;\nmy $ctx = context(); # Get a context\n$ctx->ok($bool, $name);\n$ctx->release; # Release the context\nreturn $bool;\n}\n\nSee Test2::API::Context for a list of methods available on the context object.\n\nTESTING YOUR TOOLS\nThe \"intercept { ... }\" tool lets you temporarily intercept all events generated by the test\nsystem:\n\nuse Test2::API qw/intercept/;\n\nuse My::Ok qw/myok/;\n\nmy $events = intercept {\n# These events are not displayed\nmyok(1, \"pass\");\nmyok(0, \"fail\");\n};\n\nAs of version 1.302178 this now returns an arrayref that is also an instance of\nTest2::API::InterceptResult. See the Test2::API::InterceptResult documentation for details on\nhow to best use it.\n\nOTHER API FUNCTIONS\nuse Test2::API qw{\ntest2initdone\ntest2stack\ntest2setisend\ntest2getisend\ntest2ipc\ntest2formatterset\ntest2formatter\ntest2istestingdone\n};\n\nmy $init = test2initdone();\nmy $stack = test2stack();\nmy $ipc = test2ipc();\n\ntest2formatterset($FORMATTER)\nmy $formatter = test2formatter();\n\n... And others ...\n", "subsections": [] }, "MAIN API EXPORTS": { "content": "All exports are optional. You must specify subs to import.\n\nuse Test2::API qw/context intercept runsubtest/;\n\nThis is the list of exports that are most commonly needed. If you are simply writing a tool,\nthen this is probably all you need. If you need something and you cannot find it here, then you\ncan also look at \"OTHER API EXPORTS\".\n\nThese exports lack the 'test2' prefix because of how important/common they are. Exports in the\n\"OTHER API EXPORTS\" section have the 'test2' prefix to ensure they stand out.\n\ncontext(...)\nUsage:\n\n$ctx = context()\n$ctx = context(%params)\n\nThe \"context()\" function will always return the current context. If there is already a context\nactive, it will be returned. If there is not an active context, one will be generated. When a\ncontext is generated it will default to using the file and line number where the currently\nrunning sub was called from.\n\nPlease see \"CRITICAL DETAILS\" in Test2::API::Context for important rules about what you can and\ncannot do with a context once it is obtained.\n\nNote This function will throw an exception if you ignore the context object it returns.\n\nNote On perls 5.14+ a depth check is used to insure there are no context leaks. This cannot be\nsafely done on older perls due to You\ncan forcefully enable it either by setting \"$ENV{T2CHECKDEPTH} = 1\" or\n\"$Test2::API::DODEPTHCHECK = 1\" BEFORE loading Test2::API.\n\nOPTIONAL PARAMETERS\nAll parameters to \"context\" are optional.\n\nlevel => $int\nIf you must obtain a context in a sub deeper than your entry point you can use this to tell\nit how many EXTRA stack frames to look back. If this option is not provided the default of 0\nis used.\n\nsub thirdpartytool {\nmy $sub = shift;\n... # Does not obtain a context\n$sub->();\n...\n}\n\nthirdpartytool(sub {\nmy $ctx = context(level => 1);\n...\n$ctx->release;\n});\n\nwrapped => $int\nUse this if you need to write your own tool that wraps a call to \"context()\" with the intent\nthat it should return a context object.\n\nsub mycontext {\nmy %params = ( wrapped => 0, @ );\n$params{wrapped}++;\nmy $ctx = context(%params);\n...\nreturn $ctx;\n}\n\nsub mytool {\nmy $ctx = mycontext();\n...\n$ctx->release;\n}\n\nIf you do not do this, then tools you call that also check for a context will notice that\nthe context they grabbed was created at the same stack depth, which will trigger protective\nmeasures that warn you and destroy the existing context.\n\nstack => $stack\nNormally \"context()\" looks at the global hub stack. If you are maintaining your own\nTest2::API::Stack instance you may pass it in to be used instead of the global one.\n\nhub => $hub\nUse this parameter if you want to obtain the context for a specific hub instead of whatever\none happens to be at the top of the stack.\n\noninit => sub { ... }\nThis lets you provide a callback sub that will be called ONLY if your call to \"context()\"\ngenerated a new context. The callback WILL NOT be called if \"context()\" is returning an\nexisting context. The only argument passed into the callback will be the context object\nitself.\n\nsub foo {\nmy $ctx = context(oninit => sub { 'will run' });\n\nmy $inner = sub {\n# This callback is not run since we are getting the existing\n# context from our parent sub.\nmy $ctx = context(oninit => sub { 'will NOT run' });\n$ctx->release;\n}\n$inner->();\n\n$ctx->release;\n}\n\nonrelease => sub { ... }\nThis lets you provide a callback sub that will be called when the context instance is\nreleased. This callback will be added to the returned context even if an existing context is\nreturned. If multiple calls to context add callbacks, then all will be called in reverse\norder when the context is finally released.\n\nsub foo {\nmy $ctx = context(onrelease => sub { 'will run second' });\n\nmy $inner = sub {\nmy $ctx = context(onrelease => sub { 'will run first' });\n\n# Neither callback runs on this release\n$ctx->release;\n}\n$inner->();\n\n# Both callbacks run here.\n$ctx->release;\n}\n\nrelease($;$)\nUsage:\n\nrelease $ctx;\nrelease $ctx, ...;\n\nThis is intended as a shortcut that lets you release your context and return a value in one\nstatement. This function will get your context, and an optional return value. It will release\nyour context, then return your value. Scalar context is always assumed.\n\nsub tool {\nmy $ctx = context();\n...\n\nreturn release $ctx, 1;\n}\n\nThis tool is most useful when you want to return the value you get from calling a function that\nneeds to see the current context:\n\nmy $ctx = context();\nmy $out = sometool(...);\n$ctx->release;\nreturn $out;\n\nWe can combine the last 3 lines of the above like so:\n\nmy $ctx = context();\nrelease $ctx, sometool(...);\n\ncontextdo(&;@)\nUsage:\n\nsub mytool {\ncontextdo {\nmy $ctx = shift;\n\nmy (@args) = @;\n\n$ctx->ok(1, \"pass\");\n\n...\n\n# No need to call $ctx->release, done for you on scope exit.\n} @;\n}\n\nUsing this inside your test tool takes care of a lot of boilerplate for you. It will ensure a\ncontext is acquired. It will capture and rethrow any exception. It will insure the context is\nreleased when you are done. It preserves the subroutine call context (array, scalar, void).\n\nThis is the safest way to write a test tool. The only two downsides to this are a slight\nperformance decrease, and some extra indentation in your source. If the indentation is a problem\nfor you then you can take a peek at the next section.\n\nnocontext(&;$)\nUsage:\n\nnocontext { ... };\nnocontext { ... } $hid;\nsub mytool(&) {\nmy $code = shift;\nmy $ctx = context();\n...\n\nnocontext {\n# Things in here will not see our current context, they get a new\n# one.\n\n$code->();\n};\n\n...\n$ctx->release;\n};\n\nThis tool will hide a context for the provided block of code. This means any tools run inside\nthe block will get a completely new context if they acquire one. The new context will be\ninherited by tools nested below the one that acquired it.\n\nThis will normally hide the current context for the top hub. If you need to hide the context for\na different hub you can pass in the optional $hid parameter.\n\nintercept(&)\nUsage:\n\nmy $events = intercept {\nok(1, \"pass\");\nok(0, \"fail\");\n...\n};\n\nThis function takes a codeblock as its only argument, and it has a prototype. It will execute\nthe codeblock, intercepting any generated events in the process. It will return an array\nreference with all the generated event objects. All events should be subclasses of Test2::Event.\n\nAs of version 1.302178 the events array that is returned is blssed as an\nTest2::API::InterceptResult instance. Test2::API::InterceptResult Provides a helpful interface\nfor filtering and/or inspecting the events list overall, or individual events within the list.\n\nThis is intended to help you test your test code. This is not intended for people simply writing\ntests.\n\nrunsubtest(...)\nUsage:\n\nrunsubtest($NAME, \\&CODE, $BUFFERED, @ARGS)\n\n# or\n\nrunsubtest($NAME, \\&CODE, \\%PARAMS, @ARGS)\n\nThis will run the provided codeblock with the args in @args. This codeblock will be run as a\nsubtest. A subtest is an isolated test state that is condensed into a single\nTest2::Event::Subtest event, which contains all events generated inside the subtest.\n\nARGUMENTS:\n$NAME\nThe name of the subtest.\n\n\\&CODE\nThe code to run inside the subtest.\n\n$BUFFERED or \\%PARAMS\nIf this is a simple scalar then it will be treated as a boolean for the 'buffered' setting.\nIf this is a hash reference then it will be used as a parameters hash. The param hash will\nbe used for hub construction (with the specified keys removed).\n\nKeys that are removed and used by runsubtest:\n\n'buffered' => $bool\nToggle buffered status.\n\n'inherittrace' => $bool\nNormally the subtest hub is pushed and the sub is allowed to generate its own root\ncontext for the hub. When this setting is turned on a root context will be created for\nthe hub that shares the same trace as the current context.\n\nSet this to true if your tool is producing subtests without user-specified subs.\n\n'nofork' => $bool\nDefaults to off. Normally forking inside a subtest will actually fork the subtest,\nresulting in 2 final subtest events. This parameter will turn off that behavior, only\nthe original process/thread will return a final subtest event.\n\n@ARGS\nAny extra arguments you want passed into the subtest code.\n\nBUFFERED VS UNBUFFERED (OR STREAMED)\nNormally all events inside and outside a subtest are sent to the formatter immediately by the\nhub. Sometimes it is desirable to hold off sending events within a subtest until the subtest is\ncomplete. This usually depends on the formatter being used.\n\nThings not effected by this flag\nIn both cases events are generated and stored in an array. This array is eventually used to\npopulate the \"subevents\" attribute on the Test2::Event::Subtest event that is generated at\nthe end of the subtest. This flag has no effect on this part, it always happens.\n\nAt the end of the subtest, the final Test2::Event::Subtest event is sent to the formatter.\n\nThings that are effected by this flag\nThe \"buffered\" attribute of the Test2::Event::Subtest event will be set to the value of this\nflag. This means any formatter, listener, etc which looks at the event will know if it was\nbuffered.\n\nThings that are formatter dependant\nEvents within a buffered subtest may or may not be sent to the formatter as they happen. If\na formatter fails to specify then the default is to NOT SEND the events as they are\ngenerated, instead the formatter can pull them from the \"subevents\" attribute.\n\nA formatter can specify by implementing the \"hidebuffered()\" method. If this method returns\ntrue then events generated inside a buffered subtest will not be sent independently of the\nfinal subtest event.\n\nAn example of how this is used is the Test2::Formatter::TAP formatter. For unbuffered subtests\nthe events are rendered as they are generated. At the end of the subtest, the final subtest\nevent is rendered, but the \"subevents\" attribute is ignored. For buffered subtests the opposite\noccurs, the events are NOT rendered as they are generated, instead the \"subevents\" attribute is\nused to render them all at once. This is useful when running subtests tests in parallel, since\nwithout it the output from subtests would be interleaved together.\n", "subsections": [] }, "OTHER API EXPORTS": { "content": "Exports in this section are not commonly needed. These all have the 'test2' prefix to help\nensure they stand out. You should look at the \"MAIN API EXPORTS\" section before looking here.\nThis section is one where \"Great power comes with great responsibility\". It is possible to break\nthings badly if you are not careful with these.\n\nAll exports are optional. You need to list which ones you want at import time:\n\nuse Test2::API qw/test2initdone .../;\n\nSTATUS AND INITIALIZATION STATE\nThese provide access to internal state and object instances.\n\n$bool = test2initdone()\nThis will return true if the stack and IPC instances have already been initialized. It will\nreturn false if they have not. Init happens as late as possible. It happens as soon as a\ntool requests the IPC instance, the formatter, or the stack.\n\n$bool = test2loaddone()\nThis will simply return the boolean value of the loaded flag. If Test2 has finished loading\nthis will be true, otherwise false. Loading is considered complete the first time a tool\nrequests a context.\n", "subsections": [ { "name": "test2_set_is_end", "content": "" }, { "name": "test2_set_is_end", "content": "This is used to toggle Test2's belief that the END phase has already started. With no\narguments this will set it to true. With arguments it will set it to the first argument's\nvalue.\n\nThis is used to prevent the use of \"caller()\" in END blocks which can cause segfaults. This\nis only necessary in some persistent environments that may have multiple END phases.\n\n$bool = test2getisend()\nCheck if Test2 believes it is the END phase.\n\n$stack = test2stack()\nThis will return the global Test2::API::Stack instance. If this has not yet been initialized\nit will be initialized now.\n\n$bool = test2istestingdone()\nThis will return true if testing is complete and no other events should be sent. This is\nuseful in things like warning handlers where you might want to turn warnings into events,\nbut need them to start acting like normal warnings when testing is done.\n\n$SIG{WARN} = sub {\nmy ($warning) = @;\n\nif (test2istestingdone()) {\nwarn @;\n}\nelse {\nmy $ctx = context();\n...\n$ctx->release\n}\n}\n\ntest2ipcdisable\nDisable IPC.\n\n$bool = test2ipcdiabled\nCheck if IPC is disabled.\n" }, { "name": "test2_ipc_wait_enable", "content": "" }, { "name": "test2_ipc_wait_disable", "content": "$bool = test2ipcwaitenabled()\nThese can be used to turn IPC waiting on and off, or check the current value of the flag.\n\nWaiting is turned on by default. Waiting will cause the parent process/thread to wait until\nall child processes and threads are finished before exiting. You will almost never want to\nturn this off.\n\n$bool = test2nowait()" }, { "name": "test2_no_wait", "content": "DISCOURAGED: This is a confusing interface, it is better to use \"test2ipcwaitenable()\",\n\"test2ipcwaitdisable()\" and \"test2ipcwaitenabled()\".\n\nThis can be used to get/set the nowait status. Waiting is turned on by default. Waiting\nwill cause the parent process/thread to wait until all child processes and threads are\nfinished before exiting. You will almost never want to turn this off.\n\n$fh = test2stdout()\n$fh = test2stderr()\nThese functions return the filehandles that test output should be written to. They are\nprimarily useful when writing a custom formatter and code that turns events into actual\noutput (TAP, etc.). They will return a dupe of the original filehandles that formatted\noutput can be sent to regardless of whatever state the currently running test may have left\nSTDOUT and STDERR in.\n" }, { "name": "test2_reset_io", "content": "Re-dupe the internal filehandles returned by \"test2stdout()\" and \"test2stderr()\" from the\ncurrent STDOUT and STDERR. You shouldn't need to do this except in very peculiar situations\n(for example, you're testing a new formatter and you need control over where the formatter\nis sending its output.)\n\nBEHAVIOR HOOKS\nThese are hooks that allow you to add custom behavior to actions taken by Test2 and tools built\non top of it.\n" }, { "name": "test2_add_callback_exit", "content": "This can be used to add a callback that is called after all testing is done. This is too\nlate to add additional results, the main use of this callback is to set the exit code.\n\ntest2addcallbackexit(\nsub {\nmy ($context, $exit, \\$newexit) = @;\n...\n}\n);\n\nThe $context passed in will be an instance of Test2::API::Context. The $exit argument will\nbe the original exit code before anything modified it. $$newexit is a reference to the new\nexit code. You may modify this to change the exit code. Please note that $$newexit may\nalready be different from $exit\n" }, { "name": "test2_add_callback_post_load", "content": "Add a callback that will be called when Test2 is finished loading. This means the callback\nwill be run once, the first time a context is obtained. If Test2 has already finished\nloading then the callback will be run immediately.\n" }, { "name": "test2_add_callback_testing_done", "content": "This adds your coderef as a follow-up to the root hub after Test2 is finished loading.\n\nThis is essentially a helper to do the following:\n\ntest2addcallbackpostload(sub {\nmy $stack = test2stack();\n$stack->top; # Insure we have a hub\nmy ($hub) = Test2::API::test2stack->all;\n\n$hub->setactive(1);\n\n$hub->followup(sub { ... }); # <-- Your coderef here\n});\n" }, { "name": "test2_add_callback_context_acquire", "content": "Add a callback that will be called every time someone tries to acquire a context. This will\nbe called on EVERY call to \"context()\". It gets a single argument, a reference to the hash\nof parameters being used the construct the context. This is your chance to change the\nparameters by directly altering the hash.\n\ntest2addcallbackcontextacquire(sub {\nmy $params = shift;\n$params->{level}++;\n});\n\nThis is a very scary API function. Please do not use this unless you need to. This is here\nfor Test::Builder and backwards compatibility. This has you directly manipulate the hash\ninstead of returning a new one for performance reasons.\n" }, { "name": "test2_add_callback_context_init", "content": "Add a callback that will be called every time a new context is created. The callback will\nreceive the newly created context as its only argument.\n" }, { "name": "test2_add_callback_context_release", "content": "Add a callback that will be called every time a context is released. The callback will\nreceive the released context as its only argument.\n" }, { "name": "test2_add_callback_pre_subtest", "content": "Add a callback that will be called every time a subtest is going to be run. The callback\nwill receive the subtest name, coderef, and any arguments.\n\n@list = test2listcontextacquirecallbacks()\nReturn all the context acquire callback references.\n\n@list = test2listcontextinitcallbacks()\nReturns all the context init callback references.\n\n@list = test2listcontextreleasecallbacks()\nReturns all the context release callback references.\n\n@list = test2listexitcallbacks()\nReturns all the exit callback references.\n\n@list = test2listpostloadcallbacks()\nReturns all the post load callback references.\n\n@list = test2listpresubtestcallbacks()\nReturns all the pre-subtest callback references.\n" }, { "name": "test2_add_uuid_via", "content": "$sub = test2adduuidvia()\nThis allows you to provide a UUID generator. If provided UUIDs will be attached to all\nevents, hubs, and contexts. This is useful for storing, tracking, and linking these objects.\n\nThe sub you provide should always return a unique identifier. Most things will expect a\nproper UUID string, however nothing in Test2::API enforces this.\n\nThe sub will receive exactly 1 argument, the type of thing being tagged 'context', 'hub', or\n'event'. In the future additional things may be tagged, in which case new strings will be\npassed in. These are purely informative, you can (and usually should) ignore them.\n\nIPC AND CONCURRENCY\nThese let you access, or specify, the IPC system internals.\n\n$bool = test2hasipc()\nCheck if IPC is enabled.\n\n$ipc = test2ipc()\nThis will return the global Test2::IPC::Driver instance. If this has not yet been\ninitialized it will be initialized now.\n" }, { "name": "test2_ipc_add_driver", "content": "Add an IPC driver to the list. This will add the driver to the start of the list.\n\n@drivers = test2ipcdrivers()\nGet the list of IPC drivers.\n\n$bool = test2ipcpolling()\nCheck if polling is enabled.\n" }, { "name": "test2_ipc_enable_polling", "content": "Turn on polling. This will cull events from other processes and threads every time a context\nis created.\n" }, { "name": "test2_ipc_disable_polling", "content": "Turn off IPC polling.\n" }, { "name": "test2_ipc_enable_shm", "content": "Legacy, this is currently a no-op that returns 0;\n" }, { "name": "test2_ipc_set_pending", "content": "Tell other processes and events that an event is pending. $uniqval should be a unique value\nno other thread/process will generate.\n\nNote: After calling this \"test2ipcgetpending()\" will return 1. This is intentional, and\nnot avoidable.\n\n$pending = test2ipcgetpending()\nThis returns -1 if there is no way to check (assume yes)\n\nThis returns 0 if there are (most likely) no pending events.\n\nThis returns 1 if there are (likely) pending events. Upon return it will reset, nothing else\nwill be able to see that there were pending events.\n\n$timeout = test2ipcgettimeout()" }, { "name": "test2_ipc_set_timeout", "content": "Get/Set the timeout value for the IPC system. This timeout is how long the IPC system will\nwait for child processes and threads to finish before aborting.\n\nThe default value is 30 seconds.\n\nMANAGING FORMATTERS\nThese let you access, or specify, the formatters that can/should be used.\n\n$formatter = test2formatter\nThis will return the global formatter class. This is not an instance. By default the\nformatter is set to Test2::Formatter::TAP.\n\nYou can override this default using the \"T2FORMATTER\" environment variable.\n\nNormally 'Test2::Formatter::' is prefixed to the value in the environment variable:\n\n$ T2FORMATTER='TAP' perl test.t # Use the Test2::Formatter::TAP formatter\n$ T2FORMATTER='Foo' perl test.t # Use the Test2::Formatter::Foo formatter\n\nIf you want to specify a full module name you use the '+' prefix:\n\n$ T2FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter\n" }, { "name": "test2_formatter_set", "content": "Set the global formatter class. This can only be set once. Note: This will override anything\nspecified in the 'T2FORMATTER' environment variable.\n\n@formatters = test2formatters()\nGet a list of all loaded formatters.\n" }, { "name": "test2_formatter_add", "content": "Add a formatter to the list. Last formatter added is used at initialization. If this is\ncalled after initialization a warning will be issued.\n" } ] }, "OTHER EXAMPLES": { "content": "See the \"/Examples/\" directory included in this distribution.\n", "subsections": [] }, "SEE ALSO": { "content": "Test2::API::Context - Detailed documentation of the context object.\n\nTest2::IPC - The IPC system used for threading/fork support.\n\nTest2::Formatter - Formatters such as TAP live here.\n\nTest2::Event - Events live in this namespace.\n\nTest2::Hub - All events eventually funnel through a hub. Custom hubs are how \"intercept()\" and\n\"runsubtest()\" are implemented.\n", "subsections": [] }, "MAGIC": { "content": "This package has an END block. This END block is responsible for setting the exit code based on\nthe test results. This end block also calls the callbacks that can be added to this package.\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 \n", "subsections": [] }, "AUTHORS": { "content": "Chad Granum \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2020 Chad Granum .\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": [] } } } }