diff options
Diffstat (limited to 'upstream/archlinux/man3/Test2::API.3perl')
| -rw-r--r-- | upstream/archlinux/man3/Test2::API.3perl | 929 |
1 files changed, 929 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/Test2::API.3perl b/upstream/archlinux/man3/Test2::API.3perl new file mode 100644 index 00000000..c790e72f --- /dev/null +++ b/upstream/archlinux/man3/Test2::API.3perl @@ -0,0 +1,929 @@ +.\" -*- 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::API 3perl" +.TH Test2::API 3perl 2024-02-11 "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::API \- Primary interface for writing Test2 based testing tools. +.SH "***INTERNALS NOTE***" +.IX Header "***INTERNALS NOTE***" +\&\fBThe internals of this package are subject to change at any time!\fR The public +methods provided will not change in backwards-incompatible ways (once there is +a stable release), but the underlying implementation details might. +\&\fBDo not break encapsulation here!\fR +.PP +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. +.PP +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. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This package exports all the functions necessary to write and/or verify testing +tools. Using these building blocks you can begin writing test tools very +quickly. You are also provided with tools that help you to test the tools you +write. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.SS "WRITING A TOOL" +.IX Subsection "WRITING A TOOL" +The \f(CWcontext()\fR method is your primary interface into the Test2 framework. +.PP +.Vb 2 +\& package My::Ok; +\& use Test2::API qw/context/; +\& +\& our @EXPORT = qw/my_ok/; +\& use base \*(AqExporter\*(Aq; +\& +\& # Just like ok() from Test::More +\& sub my_ok($;$) { +\& my ($bool, $name) = @_; +\& my $ctx = context(); # Get a context +\& $ctx\->ok($bool, $name); +\& $ctx\->release; # Release the context +\& return $bool; +\& } +.Ve +.PP +See Test2::API::Context for a list of methods available on the context object. +.SS "TESTING YOUR TOOLS" +.IX Subsection "TESTING YOUR TOOLS" +The \f(CW\*(C`intercept { ... }\*(C'\fR tool lets you temporarily intercept all events +generated by the test system: +.PP +.Vb 1 +\& use Test2::API qw/intercept/; +\& +\& use My::Ok qw/my_ok/; +\& +\& my $events = intercept { +\& # These events are not displayed +\& my_ok(1, "pass"); +\& my_ok(0, "fail"); +\& }; +.Ve +.PP +As of version 1.302178 this now returns an arrayref that is also an instance of +Test2::API::InterceptResult. See the Test2::API::InterceptResult +documentation for details on how to best use it. +.SS "OTHER API FUNCTIONS" +.IX Subsection "OTHER API FUNCTIONS" +.Vb 10 +\& use Test2::API qw{ +\& test2_init_done +\& test2_stack +\& test2_set_is_end +\& test2_get_is_end +\& test2_ipc +\& test2_formatter_set +\& test2_formatter +\& test2_is_testing_done +\& }; +\& +\& my $init = test2_init_done(); +\& my $stack = test2_stack(); +\& my $ipc = test2_ipc(); +\& +\& test2_formatter_set($FORMATTER) +\& my $formatter = test2_formatter(); +\& +\& ... And others ... +.Ve +.SH "MAIN API EXPORTS" +.IX Header "MAIN API EXPORTS" +All exports are optional. You must specify subs to import. +.PP +.Vb 1 +\& use Test2::API qw/context intercept run_subtest/; +.Ve +.PP +This is the list of exports that are most commonly needed. If you are simply +writing a tool, then this is probably all you need. If you need something and +you cannot find it here, then you can also look at "OTHER API EXPORTS". +.PP +These exports lack the 'test2_' prefix because of how important/common they +are. Exports in the "OTHER API EXPORTS" section have the 'test2_' prefix to +ensure they stand out. +.SS context(...) +.IX Subsection "context(...)" +Usage: +.ie n .IP "$ctx = \fBcontext()\fR" 4 +.el .IP "\f(CW$ctx\fR = \fBcontext()\fR" 4 +.IX Item "$ctx = context()" +.PD 0 +.ie n .IP "$ctx = context(%params)" 4 +.el .IP "\f(CW$ctx\fR = context(%params)" 4 +.IX Item "$ctx = context(%params)" +.PD +.PP +The \f(CWcontext()\fR function will always return the current context. If +there is already a context active, it will be returned. If there is not an +active context, one will be generated. When a context is generated it will +default to using the file and line number where the currently running sub was +called from. +.PP +Please see "CRITICAL DETAILS" in Test2::API::Context for important rules about +what you can and cannot do with a context once it is obtained. +.PP +\&\fBNote\fR This function will throw an exception if you ignore the context object +it returns. +.PP +\&\fBNote\fR On perls 5.14+ a depth check is used to insure there are no context +leaks. This cannot be safely done on older perls due to +<https://rt.perl.org/Public/Bug/Display.html?id=127774> +You can forcefully enable it either by setting \f(CW\*(C`$ENV{T2_CHECK_DEPTH} = 1\*(C'\fR or +\&\f(CW\*(C`$Test2::API::DO_DEPTH_CHECK = 1\*(C'\fR \fBBEFORE\fR loading Test2::API. +.PP +\fIOPTIONAL PARAMETERS\fR +.IX Subsection "OPTIONAL PARAMETERS" +.PP +All parameters to \f(CW\*(C`context\*(C'\fR are optional. +.ie n .IP "level => $int" 4 +.el .IP "level => \f(CW$int\fR" 4 +.IX Item "level => $int" +If you must obtain a context in a sub deeper than your entry point you can use +this to tell it how many EXTRA stack frames to look back. If this option is not +provided the default of \f(CW0\fR is used. +.Sp +.Vb 6 +\& sub third_party_tool { +\& my $sub = shift; +\& ... # Does not obtain a context +\& $sub\->(); +\& ... +\& } +\& +\& third_party_tool(sub { +\& my $ctx = context(level => 1); +\& ... +\& $ctx\->release; +\& }); +.Ve +.ie n .IP "wrapped => $int" 4 +.el .IP "wrapped => \f(CW$int\fR" 4 +.IX Item "wrapped => $int" +Use this if you need to write your own tool that wraps a call to \f(CWcontext()\fR +with the intent that it should return a context object. +.Sp +.Vb 7 +\& sub my_context { +\& my %params = ( wrapped => 0, @_ ); +\& $params{wrapped}++; +\& my $ctx = context(%params); +\& ... +\& return $ctx; +\& } +\& +\& sub my_tool { +\& my $ctx = my_context(); +\& ... +\& $ctx\->release; +\& } +.Ve +.Sp +If you do not do this, then tools you call that also check for a context will +notice that the context they grabbed was created at the same stack depth, which +will trigger protective measures that warn you and destroy the existing +context. +.ie n .IP "stack => $stack" 4 +.el .IP "stack => \f(CW$stack\fR" 4 +.IX Item "stack => $stack" +Normally \f(CWcontext()\fR looks at the global hub stack. If you are maintaining +your own Test2::API::Stack instance you may pass it in to be used +instead of the global one. +.ie n .IP "hub => $hub" 4 +.el .IP "hub => \f(CW$hub\fR" 4 +.IX Item "hub => $hub" +Use this parameter if you want to obtain the context for a specific hub instead +of whatever one happens to be at the top of the stack. +.IP "on_init => sub { ... }" 4 +.IX Item "on_init => sub { ... }" +This lets you provide a callback sub that will be called \fBONLY\fR if your call +to \f(CWcontext()\fR generated a new context. The callback \fBWILL NOT\fR be called if +\&\f(CWcontext()\fR is returning an existing context. The only argument passed into +the callback will be the context object itself. +.Sp +.Vb 2 +\& sub foo { +\& my $ctx = context(on_init => sub { \*(Aqwill run\*(Aq }); +\& +\& my $inner = sub { +\& # This callback is not run since we are getting the existing +\& # context from our parent sub. +\& my $ctx = context(on_init => sub { \*(Aqwill NOT run\*(Aq }); +\& $ctx\->release; +\& } +\& $inner\->(); +\& +\& $ctx\->release; +\& } +.Ve +.IP "on_release => sub { ... }" 4 +.IX Item "on_release => sub { ... }" +This lets you provide a callback sub that will be called when the context +instance is released. This callback will be added to the returned context even +if an existing context is returned. If multiple calls to context add callbacks, +then all will be called in reverse order when the context is finally released. +.Sp +.Vb 2 +\& sub foo { +\& my $ctx = context(on_release => sub { \*(Aqwill run second\*(Aq }); +\& +\& my $inner = sub { +\& my $ctx = context(on_release => sub { \*(Aqwill run first\*(Aq }); +\& +\& # Neither callback runs on this release +\& $ctx\->release; +\& } +\& $inner\->(); +\& +\& # Both callbacks run here. +\& $ctx\->release; +\& } +.Ve +.SS release($;$) +.IX Subsection "release($;$)" +Usage: +.ie n .IP "release $ctx;" 4 +.el .IP "release \f(CW$ctx\fR;" 4 +.IX Item "release $ctx;" +.PD 0 +.ie n .IP "release $ctx, ...;" 4 +.el .IP "release \f(CW$ctx\fR, ...;" 4 +.IX Item "release $ctx, ...;" +.PD +.PP +This is intended as a shortcut that lets you release your context and return a +value in one statement. This function will get your context, and an optional +return value. It will release your context, then return your value. Scalar +context is always assumed. +.PP +.Vb 3 +\& sub tool { +\& my $ctx = context(); +\& ... +\& +\& return release $ctx, 1; +\& } +.Ve +.PP +This tool is most useful when you want to return the value you get from calling +a function that needs to see the current context: +.PP +.Vb 4 +\& my $ctx = context(); +\& my $out = some_tool(...); +\& $ctx\->release; +\& return $out; +.Ve +.PP +We can combine the last 3 lines of the above like so: +.PP +.Vb 2 +\& my $ctx = context(); +\& release $ctx, some_tool(...); +.Ve +.SS context_do(&;@) +.IX Subsection "context_do(&;@)" +Usage: +.PP +.Vb 3 +\& sub my_tool { +\& context_do { +\& my $ctx = shift; +\& +\& my (@args) = @_; +\& +\& $ctx\->ok(1, "pass"); +\& +\& ... +\& +\& # No need to call $ctx\->release, done for you on scope exit. +\& } @_; +\& } +.Ve +.PP +Using this inside your test tool takes care of a lot of boilerplate for you. It +will ensure a context is acquired. It will capture and rethrow any exception. It +will insure the context is released when you are done. It preserves the +subroutine call context (array, scalar, void). +.PP +This is the safest way to write a test tool. The only two downsides to this are a +slight performance decrease, and some extra indentation in your source. If the +indentation is a problem for you then you can take a peek at the next section. +.SS no_context(&;$) +.IX Subsection "no_context(&;$)" +Usage: +.IP "no_context { ... };" 4 +.IX Item "no_context { ... };" +.PD 0 +.ie n .IP "no_context { ... } $hid;" 4 +.el .IP "no_context { ... } \f(CW$hid\fR;" 4 +.IX Item "no_context { ... } $hid;" +.PD +.Vb 4 +\& sub my_tool(&) { +\& my $code = shift; +\& my $ctx = context(); +\& ... +\& +\& no_context { +\& # Things in here will not see our current context, they get a new +\& # one. +\& +\& $code\->(); +\& }; +\& +\& ... +\& $ctx\->release; +\& }; +.Ve +.PP +This tool will hide a context for the provided block of code. This means any +tools run inside the block will get a completely new context if they acquire +one. The new context will be inherited by tools nested below the one that +acquired it. +.PP +This will normally hide the current context for the top hub. If you need to +hide the context for a different hub you can pass in the optional \f(CW$hid\fR +parameter. +.SS intercept(&) +.IX Subsection "intercept(&)" +Usage: +.PP +.Vb 5 +\& my $events = intercept { +\& ok(1, "pass"); +\& ok(0, "fail"); +\& ... +\& }; +.Ve +.PP +This function takes a codeblock as its only argument, and it has a prototype. +It will execute the codeblock, intercepting any generated events in the +process. It will return an array reference with all the generated event +objects. All events should be subclasses of Test2::Event. +.PP +As of version 1.302178 the events array that is returned is blssed as an +Test2::API::InterceptResult instance. Test2::API::InterceptResult +Provides a helpful interface for filtering and/or inspecting the events list +overall, or individual events within the list. +.PP +This is intended to help you test your test code. This is not intended for +people simply writing tests. +.SS run_subtest(...) +.IX Subsection "run_subtest(...)" +Usage: +.PP +.Vb 1 +\& run_subtest($NAME, \e&CODE, $BUFFERED, @ARGS) +\& +\& # or +\& +\& run_subtest($NAME, \e&CODE, \e%PARAMS, @ARGS) +.Ve +.PP +This will run the provided codeblock with the args in \f(CW@args\fR. This codeblock +will be run as a subtest. A subtest is an isolated test state that is condensed +into a single Test2::Event::Subtest event, which contains all events +generated inside the subtest. +.PP +\fIARGUMENTS:\fR +.IX Subsection "ARGUMENTS:" +.ie n .IP $NAME 4 +.el .IP \f(CW$NAME\fR 4 +.IX Item "$NAME" +The name of the subtest. +.IP \e&CODE 4 +.IX Item "&CODE" +The code to run inside the subtest. +.ie n .IP "$BUFFERED or \e%PARAMS" 4 +.el .IP "\f(CW$BUFFERED\fR or \e%PARAMS" 4 +.IX Item "$BUFFERED or %PARAMS" +If this is a simple scalar then it will be treated as a boolean for the +\&'buffered' setting. If this is a hash reference then it will be used as a +parameters hash. The param hash will be used for hub construction (with the +specified keys removed). +.Sp +Keys that are removed and used by run_subtest: +.RS 4 +.ie n .IP "'buffered' => $bool" 4 +.el .IP "'buffered' => \f(CW$bool\fR" 4 +.IX Item "'buffered' => $bool" +Toggle buffered status. +.ie n .IP "'inherit_trace' => $bool" 4 +.el .IP "'inherit_trace' => \f(CW$bool\fR" 4 +.IX Item "'inherit_trace' => $bool" +Normally the subtest hub is pushed and the sub is allowed to generate its own +root context for the hub. When this setting is turned on a root context will be +created for the hub that shares the same trace as the current context. +.Sp +Set this to true if your tool is producing subtests without user-specified +subs. +.ie n .IP "'no_fork' => $bool" 4 +.el .IP "'no_fork' => \f(CW$bool\fR" 4 +.IX Item "'no_fork' => $bool" +Defaults to off. Normally forking inside a subtest will actually fork the +subtest, resulting in 2 final subtest events. This parameter will turn off that +behavior, only the original process/thread will return a final subtest event. +.RE +.RS 4 +.RE +.ie n .IP @ARGS 4 +.el .IP \f(CW@ARGS\fR 4 +.IX Item "@ARGS" +Any extra arguments you want passed into the subtest code. +.PP +\fIBUFFERED VS UNBUFFERED (OR STREAMED)\fR +.IX Subsection "BUFFERED VS UNBUFFERED (OR STREAMED)" +.PP +Normally all events inside and outside a subtest are sent to the formatter +immediately by the hub. Sometimes it is desirable to hold off sending events +within a subtest until the subtest is complete. This usually depends on the +formatter being used. +.IP "Things not effected by this flag" 4 +.IX Item "Things not effected by this flag" +In both cases events are generated and stored in an array. This array is +eventually used to populate the \f(CW\*(C`subevents\*(C'\fR attribute on the +Test2::Event::Subtest event that is generated at the end of the subtest. +This flag has no effect on this part, it always happens. +.Sp +At the end of the subtest, the final Test2::Event::Subtest event is sent to +the formatter. +.IP "Things that are effected by this flag" 4 +.IX Item "Things that are effected by this flag" +The \f(CW\*(C`buffered\*(C'\fR attribute of the Test2::Event::Subtest event will be set to +the value of this flag. This means any formatter, listener, etc which looks at +the event will know if it was buffered. +.IP "Things that are formatter dependant" 4 +.IX Item "Things that are formatter dependant" +Events within a buffered subtest may or may not be sent to the formatter as +they happen. If a formatter fails to specify then the default is to \fBNOT SEND\fR +the events as they are generated, instead the formatter can pull them from the +\&\f(CW\*(C`subevents\*(C'\fR attribute. +.Sp +A formatter can specify by implementing the \f(CWhide_buffered()\fR method. If this +method returns true then events generated inside a buffered subtest will not be +sent independently of the final subtest event. +.PP +An example of how this is used is the Test2::Formatter::TAP formatter. For +unbuffered subtests the events are rendered as they are generated. At the end +of the subtest, the final subtest event is rendered, but the \f(CW\*(C`subevents\*(C'\fR +attribute is ignored. For buffered subtests the opposite occurs, the events are +NOT rendered as they are generated, instead the \f(CW\*(C`subevents\*(C'\fR attribute is used +to render them all at once. This is useful when running subtests tests in +parallel, since without it the output from subtests would be interleaved +together. +.SH "OTHER API EXPORTS" +.IX Header "OTHER API EXPORTS" +Exports in this section are not commonly needed. These all have the 'test2_' +prefix to help ensure they stand out. You should look at the "MAIN API +EXPORTS" section before looking here. This section is one where "Great power +comes with great responsibility". It is possible to break things badly if you +are not careful with these. +.PP +All exports are optional. You need to list which ones you want at import time: +.PP +.Vb 1 +\& use Test2::API qw/test2_init_done .../; +.Ve +.SS "STATUS AND INITIALIZATION STATE" +.IX Subsection "STATUS AND INITIALIZATION STATE" +These provide access to internal state and object instances. +.ie n .IP "$bool = \fBtest2_init_done()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_init_done()\fR" 4 +.IX Item "$bool = test2_init_done()" +This will return true if the stack and IPC instances have already been +initialized. It will return false if they have not. Init happens as late as +possible. It happens as soon as a tool requests the IPC instance, the +formatter, or the stack. +.ie n .IP "$bool = \fBtest2_load_done()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_load_done()\fR" 4 +.IX Item "$bool = test2_load_done()" +This will simply return the boolean value of the loaded flag. If Test2 has +finished loading this will be true, otherwise false. Loading is considered +complete the first time a tool requests a context. +.IP \fBtest2_set_is_end()\fR 4 +.IX Item "test2_set_is_end()" +.PD 0 +.IP test2_set_is_end($bool) 4 +.IX Item "test2_set_is_end($bool)" +.PD +This is used to toggle Test2's belief that the END phase has already started. +With no arguments this will set it to true. With arguments it will set it to +the first argument's value. +.Sp +This is used to prevent the use of \f(CWcaller()\fR in END blocks which can cause +segfaults. This is only necessary in some persistent environments that may have +multiple END phases. +.ie n .IP "$bool = \fBtest2_get_is_end()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_get_is_end()\fR" 4 +.IX Item "$bool = test2_get_is_end()" +Check if Test2 believes it is the END phase. +.ie n .IP "$stack = \fBtest2_stack()\fR" 4 +.el .IP "\f(CW$stack\fR = \fBtest2_stack()\fR" 4 +.IX Item "$stack = test2_stack()" +This will return the global Test2::API::Stack instance. If this has not +yet been initialized it will be initialized now. +.ie n .IP "$bool = \fBtest2_is_testing_done()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_is_testing_done()\fR" 4 +.IX Item "$bool = test2_is_testing_done()" +This will return true if testing is complete and no other events should be +sent. This is useful in things like warning handlers where you might want to +turn warnings into events, but need them to start acting like normal warnings +when testing is done. +.Sp +.Vb 2 +\& $SIG{_\|_WARN_\|_} = sub { +\& my ($warning) = @_; +\& +\& if (test2_is_testing_done()) { +\& warn @_; +\& } +\& else { +\& my $ctx = context(); +\& ... +\& $ctx\->release +\& } +\& } +.Ve +.IP test2_ipc_disable 4 +.IX Item "test2_ipc_disable" +Disable IPC. +.ie n .IP "$bool = test2_ipc_diabled" 4 +.el .IP "\f(CW$bool\fR = test2_ipc_diabled" 4 +.IX Item "$bool = test2_ipc_diabled" +Check if IPC is disabled. +.IP \fBtest2_ipc_wait_enable()\fR 4 +.IX Item "test2_ipc_wait_enable()" +.PD 0 +.IP \fBtest2_ipc_wait_disable()\fR 4 +.IX Item "test2_ipc_wait_disable()" +.ie n .IP "$bool = \fBtest2_ipc_wait_enabled()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_ipc_wait_enabled()\fR" 4 +.IX Item "$bool = test2_ipc_wait_enabled()" +.PD +These can be used to turn IPC waiting on and off, or check the current value of +the flag. +.Sp +Waiting is turned on by default. Waiting will cause the parent process/thread +to wait until all child processes and threads are finished before exiting. You +will almost never want to turn this off. +.ie n .IP "$bool = \fBtest2_no_wait()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_no_wait()\fR" 4 +.IX Item "$bool = test2_no_wait()" +.PD 0 +.IP test2_no_wait($bool) 4 +.IX Item "test2_no_wait($bool)" +.PD +\&\fBDISCOURAGED\fR: This is a confusing interface, it is better to use +\&\f(CWtest2_ipc_wait_enable()\fR, \f(CWtest2_ipc_wait_disable()\fR and +\&\f(CWtest2_ipc_wait_enabled()\fR. +.Sp +This can be used to get/set the no_wait status. Waiting is turned on by +default. Waiting will cause the parent process/thread to wait until all child +processes and threads are finished before exiting. You will almost never want +to turn this off. +.ie n .IP "$fh = \fBtest2_stdout()\fR" 4 +.el .IP "\f(CW$fh\fR = \fBtest2_stdout()\fR" 4 +.IX Item "$fh = test2_stdout()" +.PD 0 +.ie n .IP "$fh = \fBtest2_stderr()\fR" 4 +.el .IP "\f(CW$fh\fR = \fBtest2_stderr()\fR" 4 +.IX Item "$fh = test2_stderr()" +.PD +These functions return the filehandles that test output should be written to. +They are primarily useful when writing a custom formatter and code that turns +events into actual output (TAP, etc.). They will return a dupe of the original +filehandles that formatted output can be sent to regardless of whatever state +the currently running test may have left STDOUT and STDERR in. +.IP \fBtest2_reset_io()\fR 4 +.IX Item "test2_reset_io()" +Re-dupe the internal filehandles returned by \f(CWtest2_stdout()\fR and +\&\f(CWtest2_stderr()\fR from the current STDOUT and STDERR. You shouldn't need to do +this except in very peculiar situations (for example, you're testing a new +formatter and you need control over where the formatter is sending its output.) +.SS "BEHAVIOR HOOKS" +.IX Subsection "BEHAVIOR HOOKS" +These are hooks that allow you to add custom behavior to actions taken by Test2 +and tools built on top of it. +.IP "test2_add_callback_exit(sub { ... })" 4 +.IX Item "test2_add_callback_exit(sub { ... })" +This can be used to add a callback that is called after all testing is done. This +is too late to add additional results, the main use of this callback is to set the +exit code. +.Sp +.Vb 6 +\& test2_add_callback_exit( +\& sub { +\& my ($context, $exit, \e$new_exit) = @_; +\& ... +\& } +\& ); +.Ve +.Sp +The \f(CW$context\fR passed in will be an instance of Test2::API::Context. The +\&\f(CW$exit\fR argument will be the original exit code before anything modified it. +\&\f(CW$$new_exit\fR is a reference to the new exit code. You may modify this to +change the exit code. Please note that \f(CW$$new_exit\fR may already be different +from \f(CW$exit\fR +.IP "test2_add_callback_post_load(sub { ... })" 4 +.IX Item "test2_add_callback_post_load(sub { ... })" +Add a callback that will be called when Test2 is finished loading. This +means the callback will be run once, the first time a context is obtained. +If Test2 has already finished loading then the callback will be run immediately. +.IP "test2_add_callback_testing_done(sub { ... })" 4 +.IX Item "test2_add_callback_testing_done(sub { ... })" +This adds your coderef as a follow-up to the root hub after Test2 is finished loading. +.Sp +This is essentially a helper to do the following: +.Sp +.Vb 4 +\& test2_add_callback_post_load(sub { +\& my $stack = test2_stack(); +\& $stack\->top; # Insure we have a hub +\& my ($hub) = Test2::API::test2_stack\->all; +\& +\& $hub\->set_active(1); +\& +\& $hub\->follow_up(sub { ... }); # <\-\- Your coderef here +\& }); +.Ve +.IP "test2_add_callback_context_acquire(sub { ... })" 4 +.IX Item "test2_add_callback_context_acquire(sub { ... })" +Add a callback that will be called every time someone tries to acquire a +context. This will be called on EVERY call to \f(CWcontext()\fR. It gets a single +argument, a reference to the hash of parameters being used the construct the +context. This is your chance to change the parameters by directly altering the +hash. +.Sp +.Vb 4 +\& test2_add_callback_context_acquire(sub { +\& my $params = shift; +\& $params\->{level}++; +\& }); +.Ve +.Sp +This is a very scary API function. Please do not use this unless you need to. +This is here for Test::Builder and backwards compatibility. This has you +directly manipulate the hash instead of returning a new one for performance +reasons. +.IP "test2_add_callback_context_init(sub { ... })" 4 +.IX Item "test2_add_callback_context_init(sub { ... })" +Add a callback that will be called every time a new context is created. The +callback will receive the newly created context as its only argument. +.IP "test2_add_callback_context_release(sub { ... })" 4 +.IX Item "test2_add_callback_context_release(sub { ... })" +Add a callback that will be called every time a context is released. The +callback will receive the released context as its only argument. +.IP "test2_add_callback_pre_subtest(sub { ... })" 4 +.IX Item "test2_add_callback_pre_subtest(sub { ... })" +Add a callback that will be called every time a subtest is going to be +run. The callback will receive the subtest name, coderef, and any +arguments. +.ie n .IP "@list = \fBtest2_list_context_acquire_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_context_acquire_callbacks()\fR" 4 +.IX Item "@list = test2_list_context_acquire_callbacks()" +Return all the context acquire callback references. +.ie n .IP "@list = \fBtest2_list_context_init_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_context_init_callbacks()\fR" 4 +.IX Item "@list = test2_list_context_init_callbacks()" +Returns all the context init callback references. +.ie n .IP "@list = \fBtest2_list_context_release_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_context_release_callbacks()\fR" 4 +.IX Item "@list = test2_list_context_release_callbacks()" +Returns all the context release callback references. +.ie n .IP "@list = \fBtest2_list_exit_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_exit_callbacks()\fR" 4 +.IX Item "@list = test2_list_exit_callbacks()" +Returns all the exit callback references. +.ie n .IP "@list = \fBtest2_list_post_load_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_post_load_callbacks()\fR" 4 +.IX Item "@list = test2_list_post_load_callbacks()" +Returns all the post load callback references. +.ie n .IP "@list = \fBtest2_list_pre_subtest_callbacks()\fR" 4 +.el .IP "\f(CW@list\fR = \fBtest2_list_pre_subtest_callbacks()\fR" 4 +.IX Item "@list = test2_list_pre_subtest_callbacks()" +Returns all the pre-subtest callback references. +.IP "test2_add_uuid_via(sub { ... })" 4 +.IX Item "test2_add_uuid_via(sub { ... })" +.PD 0 +.ie n .IP "$sub = \fBtest2_add_uuid_via()\fR" 4 +.el .IP "\f(CW$sub\fR = \fBtest2_add_uuid_via()\fR" 4 +.IX Item "$sub = test2_add_uuid_via()" +.PD +This allows you to provide a UUID generator. If provided UUIDs will be attached +to all events, hubs, and contexts. This is useful for storing, tracking, and +linking these objects. +.Sp +The sub you provide should always return a unique identifier. Most things will +expect a proper UUID string, however nothing in Test2::API enforces this. +.Sp +The sub will receive exactly 1 argument, the type of thing being tagged +\&'context', 'hub', or 'event'. In the future additional things may be tagged, in +which case new strings will be passed in. These are purely informative, you can +(and usually should) ignore them. +.SS "IPC AND CONCURRENCY" +.IX Subsection "IPC AND CONCURRENCY" +These let you access, or specify, the IPC system internals. +.ie n .IP "$bool = \fBtest2_has_ipc()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_has_ipc()\fR" 4 +.IX Item "$bool = test2_has_ipc()" +Check if IPC is enabled. +.ie n .IP "$ipc = \fBtest2_ipc()\fR" 4 +.el .IP "\f(CW$ipc\fR = \fBtest2_ipc()\fR" 4 +.IX Item "$ipc = test2_ipc()" +This will return the global Test2::IPC::Driver instance. If this has not yet +been initialized it will be initialized now. +.IP test2_ipc_add_driver($DRIVER) 4 +.IX Item "test2_ipc_add_driver($DRIVER)" +Add an IPC driver to the list. This will add the driver to the start of the +list. +.ie n .IP "@drivers = \fBtest2_ipc_drivers()\fR" 4 +.el .IP "\f(CW@drivers\fR = \fBtest2_ipc_drivers()\fR" 4 +.IX Item "@drivers = test2_ipc_drivers()" +Get the list of IPC drivers. +.ie n .IP "$bool = \fBtest2_ipc_polling()\fR" 4 +.el .IP "\f(CW$bool\fR = \fBtest2_ipc_polling()\fR" 4 +.IX Item "$bool = test2_ipc_polling()" +Check if polling is enabled. +.IP \fBtest2_ipc_enable_polling()\fR 4 +.IX Item "test2_ipc_enable_polling()" +Turn on polling. This will cull events from other processes and threads every +time a context is created. +.IP \fBtest2_ipc_disable_polling()\fR 4 +.IX Item "test2_ipc_disable_polling()" +Turn off IPC polling. +.IP \fBtest2_ipc_enable_shm()\fR 4 +.IX Item "test2_ipc_enable_shm()" +Legacy, this is currently a no-op that returns 0; +.IP test2_ipc_set_pending($uniq_val) 4 +.IX Item "test2_ipc_set_pending($uniq_val)" +Tell other processes and events that an event is pending. \f(CW$uniq_val\fR should +be a unique value no other thread/process will generate. +.Sp +\&\fBNote:\fR After calling this \f(CWtest2_ipc_get_pending()\fR will return 1. This is +intentional, and not avoidable. +.ie n .IP "$pending = \fBtest2_ipc_get_pending()\fR" 4 +.el .IP "\f(CW$pending\fR = \fBtest2_ipc_get_pending()\fR" 4 +.IX Item "$pending = test2_ipc_get_pending()" +This returns \-1 if there is no way to check (assume yes) +.Sp +This returns 0 if there are (most likely) no pending events. +.Sp +This returns 1 if there are (likely) pending events. Upon return it will reset, +nothing else will be able to see that there were pending events. +.ie n .IP "$timeout = \fBtest2_ipc_get_timeout()\fR" 4 +.el .IP "\f(CW$timeout\fR = \fBtest2_ipc_get_timeout()\fR" 4 +.IX Item "$timeout = test2_ipc_get_timeout()" +.PD 0 +.IP test2_ipc_set_timeout($timeout) 4 +.IX Item "test2_ipc_set_timeout($timeout)" +.PD +Get/Set the timeout value for the IPC system. This timeout is how long the IPC +system will wait for child processes and threads to finish before aborting. +.Sp +The default value is \f(CW30\fR seconds. +.SS "MANAGING FORMATTERS" +.IX Subsection "MANAGING FORMATTERS" +These let you access, or specify, the formatters that can/should be used. +.ie n .IP "$formatter = test2_formatter" 4 +.el .IP "\f(CW$formatter\fR = test2_formatter" 4 +.IX Item "$formatter = test2_formatter" +This will return the global formatter class. This is not an instance. By +default the formatter is set to Test2::Formatter::TAP. +.Sp +You can override this default using the \f(CW\*(C`T2_FORMATTER\*(C'\fR environment variable. +.Sp +Normally 'Test2::Formatter::' is prefixed to the value in the +environment variable: +.Sp +.Vb 2 +\& $ T2_FORMATTER=\*(AqTAP\*(Aq perl test.t # Use the Test2::Formatter::TAP formatter +\& $ T2_FORMATTER=\*(AqFoo\*(Aq perl test.t # Use the Test2::Formatter::Foo formatter +.Ve +.Sp +If you want to specify a full module name you use the '+' prefix: +.Sp +.Vb 1 +\& $ T2_FORMATTER=\*(Aq+Foo::Bar\*(Aq perl test.t # Use the Foo::Bar formatter +.Ve +.IP test2_formatter_set($class_or_instance) 4 +.IX Item "test2_formatter_set($class_or_instance)" +Set the global formatter class. This can only be set once. \fBNote:\fR This will +override anything specified in the 'T2_FORMATTER' environment variable. +.ie n .IP "@formatters = \fBtest2_formatters()\fR" 4 +.el .IP "\f(CW@formatters\fR = \fBtest2_formatters()\fR" 4 +.IX Item "@formatters = test2_formatters()" +Get a list of all loaded formatters. +.IP test2_formatter_add($class_or_instance) 4 +.IX Item "test2_formatter_add($class_or_instance)" +Add a formatter to the list. Last formatter added is used at initialization. If +this is called after initialization a warning will be issued. +.SH "OTHER EXAMPLES" +.IX Header "OTHER EXAMPLES" +See the \f(CW\*(C`/Examples/\*(C'\fR directory included in this distribution. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Test2::API::Context \- Detailed documentation of the context object. +.PP +Test2::IPC \- The IPC system used for threading/fork support. +.PP +Test2::Formatter \- Formatters such as TAP live here. +.PP +Test2::Event \- Events live in this namespace. +.PP +Test2::Hub \- All events eventually funnel through a hub. Custom hubs are how +\&\f(CWintercept()\fR and \f(CWrun_subtest()\fR are implemented. +.SH MAGIC +.IX Header "MAGIC" +This package has an END block. This END block is responsible for setting the +exit code based on the test results. This end block also calls the callbacks that +can be added to this package. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Test2 can be found at +\&\fIhttp://github.com/Test\-More/test\-more/\fR. +.SH MAINTAINERS +.IX Header "MAINTAINERS" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH AUTHORS +.IX Header "AUTHORS" +.PD 0 +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.PD +.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://dev.perl.org/licenses/\fR |