summaryrefslogtreecommitdiffstats
path: root/upstream/mageia-cauldron/man3pm/Test2::Hub.3pm
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--upstream/mageia-cauldron/man3pm/Test2::Hub.3pm443
1 files changed, 443 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test2::Hub.3pm b/upstream/mageia-cauldron/man3pm/Test2::Hub.3pm
new file mode 100644
index 00000000..d8952619
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Test2::Hub.3pm
@@ -0,0 +1,443 @@
+.\" -*- 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::Hub 3pm"
+.TH Test2::Hub 3pm 2023-11-28 "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::Hub \- The conduit through which all events flow.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use Test2::Hub;
+\&
+\& my $hub = Test2::Hub\->new();
+\& $hub\->send(...);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The hub is the place where all events get processed and handed off to the
+formatter. The hub also tracks test state, and provides several hooks into the
+event pipeline.
+.SH "COMMON TASKS"
+.IX Header "COMMON TASKS"
+.SS "SENDING EVENTS"
+.IX Subsection "SENDING EVENTS"
+.Vb 1
+\& $hub\->send($event)
+.Ve
+.PP
+The \f(CWsend()\fR method is used to issue an event to the hub. This method will
+handle thread/fork sync, filters, listeners, TAP output, etc.
+.SS "ALTERING OR REMOVING EVENTS"
+.IX Subsection "ALTERING OR REMOVING EVENTS"
+You can use either \f(CWfilter()\fR or \f(CWpre_filter()\fR, depending on your
+needs. Both have identical syntax, so only \f(CWfilter()\fR is shown here.
+.PP
+.Vb 2
+\& $hub\->filter(sub {
+\& my ($hub, $event) = @_;
+\&
+\& my $action = get_action($event);
+\&
+\& # No action should be taken
+\& return $event if $action eq \*(Aqnone\*(Aq;
+\&
+\& # You want your filter to remove the event
+\& return undef if $action eq \*(Aqdelete\*(Aq;
+\&
+\& if ($action eq \*(Aqdo_it\*(Aq) {
+\& my $new_event = copy_event($event);
+\& ... Change your copy of the event ...
+\& return $new_event;
+\& }
+\&
+\& die "Should not happen";
+\& });
+.Ve
+.PP
+By default, filters are not inherited by child hubs. That means if you start a
+subtest, the subtest will not inherit the filter. You can change this behavior
+with the \f(CW\*(C`inherit\*(C'\fR parameter:
+.PP
+.Vb 1
+\& $hub\->filter(sub { ... }, inherit => 1);
+.Ve
+.SS "LISTENING FOR EVENTS"
+.IX Subsection "LISTENING FOR EVENTS"
+.Vb 2
+\& $hub\->listen(sub {
+\& my ($hub, $event, $number) = @_;
+\&
+\& ... do whatever you want with the event ...
+\&
+\& # return is ignored
+\& });
+.Ve
+.PP
+By default listeners are not inherited by child hubs. That means if you start a
+subtest, the subtest will not inherit the listener. You can change this behavior
+with the \f(CW\*(C`inherit\*(C'\fR parameter:
+.PP
+.Vb 1
+\& $hub\->listen(sub { ... }, inherit => 1);
+.Ve
+.SS "POST-TEST BEHAVIORS"
+.IX Subsection "POST-TEST BEHAVIORS"
+.Vb 2
+\& $hub\->follow_up(sub {
+\& my ($trace, $hub) = @_;
+\&
+\& ... do whatever you need to ...
+\&
+\& # Return is ignored
+\& });
+.Ve
+.PP
+follow_up subs are called only once, either when done_testing is called, or in
+an END block.
+.SS "SETTING THE FORMATTER"
+.IX Subsection "SETTING THE FORMATTER"
+By default an instance of Test2::Formatter::TAP is created and used.
+.PP
+.Vb 1
+\& my $old = $hub\->format(My::Formatter\->new);
+.Ve
+.PP
+Setting the formatter will REPLACE any existing formatter. You may set the
+formatter to undef to prevent output. The old formatter will be returned if one
+was already set. Only one formatter is allowed at a time.
+.SH METHODS
+.IX Header "METHODS"
+.ie n .IP $hub\->send($event) 4
+.el .IP \f(CW$hub\fR\->send($event) 4
+.IX Item "$hub->send($event)"
+This is where all events enter the hub for processing.
+.ie n .IP $hub\->process($event) 4
+.el .IP \f(CW$hub\fR\->process($event) 4
+.IX Item "$hub->process($event)"
+This is called by send after it does any IPC handling. You can use this to
+bypass the IPC process, but in general you should avoid using this.
+.ie n .IP "$old = $hub\->format($formatter)" 4
+.el .IP "\f(CW$old\fR = \f(CW$hub\fR\->format($formatter)" 4
+.IX Item "$old = $hub->format($formatter)"
+Replace the existing formatter instance with a new one. Formatters must be
+objects that implement a \f(CW\*(C`$formatter\->write($event)\*(C'\fR method.
+.ie n .IP "$sub = $hub\->listen(sub { ... }, %optional_params)" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->listen(sub { ... }, \f(CW%optional_params\fR)" 4
+.IX Item "$sub = $hub->listen(sub { ... }, %optional_params)"
+You can use this to record all events AFTER they have been sent to the
+formatter. No changes made here will be meaningful, except possibly to other
+listeners.
+.Sp
+.Vb 2
+\& $hub\->listen(sub {
+\& my ($hub, $event, $number) = @_;
+\&
+\& ... do whatever you want with the event ...
+\&
+\& # return is ignored
+\& });
+.Ve
+.Sp
+Normally listeners are not inherited by child hubs such as subtests. You can
+add the \f(CW\*(C`inherit => 1\*(C'\fR parameter to allow a listener to be inherited.
+.ie n .IP $hub\->unlisten($sub) 4
+.el .IP \f(CW$hub\fR\->unlisten($sub) 4
+.IX Item "$hub->unlisten($sub)"
+You can use this to remove a listen callback. You must pass in the coderef
+returned by the \f(CWlisten()\fR method.
+.ie n .IP "$sub = $hub\->filter(sub { ... }, %optional_params)" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->filter(sub { ... }, \f(CW%optional_params\fR)" 4
+.IX Item "$sub = $hub->filter(sub { ... }, %optional_params)"
+.PD 0
+.ie n .IP "$sub = $hub\->pre_filter(sub { ... }, %optional_params)" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->pre_filter(sub { ... }, \f(CW%optional_params\fR)" 4
+.IX Item "$sub = $hub->pre_filter(sub { ... }, %optional_params)"
+.PD
+These can be used to add filters. Filters can modify, replace, or remove events
+before anything else can see them.
+.Sp
+.Vb 3
+\& $hub\->filter(
+\& sub {
+\& my ($hub, $event) = @_;
+\&
+\& return $event; # No Changes
+\& return; # Remove the event
+\&
+\& # Or you can modify an event before returning it.
+\& $event\->modify;
+\& return $event;
+\& }
+\& );
+.Ve
+.Sp
+If you are not using threads, forking, or IPC then the only difference between
+a \f(CW\*(C`filter\*(C'\fR and a \f(CW\*(C`pre_filter\*(C'\fR is that \f(CW\*(C`pre_filter\*(C'\fR subs run first. When you
+are using threads, forking, or IPC, pre_filters happen to events before they
+are sent to their destination proc/thread, ordinary filters happen only in the
+destination hub/thread.
+.Sp
+You cannot add a regular filter to a hub if the hub was created in another
+process or thread. You can always add a pre_filter.
+.ie n .IP $hub\->unfilter($sub) 4
+.el .IP \f(CW$hub\fR\->unfilter($sub) 4
+.IX Item "$hub->unfilter($sub)"
+.PD 0
+.ie n .IP $hub\->pre_unfilter($sub) 4
+.el .IP \f(CW$hub\fR\->pre_unfilter($sub) 4
+.IX Item "$hub->pre_unfilter($sub)"
+.PD
+These can be used to remove filters and pre_filters. The \f(CW$sub\fR argument is
+the reference returned by \f(CWfilter()\fR or \f(CWpre_filter()\fR.
+.ie n .IP "$hub\->follow_op(sub { ... })" 4
+.el .IP "\f(CW$hub\fR\->follow_op(sub { ... })" 4
+.IX Item "$hub->follow_op(sub { ... })"
+Use this to add behaviors that are called just before the hub is finalized. The
+only argument to your codeblock will be a Test2::EventFacet::Trace instance.
+.Sp
+.Vb 2
+\& $hub\->follow_up(sub {
+\& my ($trace, $hub) = @_;
+\&
+\& ... do whatever you need to ...
+\&
+\& # Return is ignored
+\& });
+.Ve
+.Sp
+follow_up subs are called only once, ether when done_testing is called, or in
+an END block.
+.ie n .IP "$sub = $hub\->add_context_acquire(sub { ... });" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_acquire(sub { ... });" 4
+.IX Item "$sub = $hub->add_context_acquire(sub { ... });"
+Add a callback that will be called every time someone tries to acquire a
+context. It gets a single argument, a reference of 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.
+.Sp
+\&\fBNote\fR Using this hook could have a huge performance impact.
+.Sp
+The coderef you provide is returned and can be used to remove the hook later.
+.ie n .IP $hub\->remove_context_acquire($sub); 4
+.el .IP \f(CW$hub\fR\->remove_context_acquire($sub); 4
+.IX Item "$hub->remove_context_acquire($sub);"
+This can be used to remove a context acquire hook.
+.ie n .IP "$sub = $hub\->add_context_init(sub { ... });" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_init(sub { ... });" 4
+.IX Item "$sub = $hub->add_context_init(sub { ... });"
+This allows you to add callbacks that will trigger every time a new context is
+created for the hub. The only argument to the sub will be the
+Test2::API::Context instance that was created.
+.Sp
+\&\fBNote\fR Using this hook could have a huge performance impact.
+.Sp
+The coderef you provide is returned and can be used to remove the hook later.
+.ie n .IP $hub\->remove_context_init($sub); 4
+.el .IP \f(CW$hub\fR\->remove_context_init($sub); 4
+.IX Item "$hub->remove_context_init($sub);"
+This can be used to remove a context init hook.
+.ie n .IP "$sub = $hub\->add_context_release(sub { ... });" 4
+.el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_release(sub { ... });" 4
+.IX Item "$sub = $hub->add_context_release(sub { ... });"
+This allows you to add callbacks that will trigger every time a context for
+this hub is released. The only argument to the sub will be the
+Test2::API::Context instance that was released. These will run in reverse
+order.
+.Sp
+\&\fBNote\fR Using this hook could have a huge performance impact.
+.Sp
+The coderef you provide is returned and can be used to remove the hook later.
+.ie n .IP $hub\->remove_context_release($sub); 4
+.el .IP \f(CW$hub\fR\->remove_context_release($sub); 4
+.IX Item "$hub->remove_context_release($sub);"
+This can be used to remove a context release hook.
+.ie n .IP $hub\->\fBcull()\fR 4
+.el .IP \f(CW$hub\fR\->\fBcull()\fR 4
+.IX Item "$hub->cull()"
+Cull any IPC events (and process them).
+.ie n .IP "$pid = $hub\->\fBpid()\fR" 4
+.el .IP "\f(CW$pid\fR = \f(CW$hub\fR\->\fBpid()\fR" 4
+.IX Item "$pid = $hub->pid()"
+Get the process id under which the hub was created.
+.ie n .IP "$tid = $hub\->\fBtid()\fR" 4
+.el .IP "\f(CW$tid\fR = \f(CW$hub\fR\->\fBtid()\fR" 4
+.IX Item "$tid = $hub->tid()"
+Get the thread id under which the hub was created.
+.ie n .IP "$hud = $hub\->\fBhid()\fR" 4
+.el .IP "\f(CW$hud\fR = \f(CW$hub\fR\->\fBhid()\fR" 4
+.IX Item "$hud = $hub->hid()"
+Get the identifier string of the hub.
+.ie n .IP "$uuid = $hub\->\fBuuid()\fR" 4
+.el .IP "\f(CW$uuid\fR = \f(CW$hub\fR\->\fBuuid()\fR" 4
+.IX Item "$uuid = $hub->uuid()"
+If UUID tagging is enabled (see Test2::API) then the hub will have a UUID.
+.ie n .IP "$ipc = $hub\->\fBipc()\fR" 4
+.el .IP "\f(CW$ipc\fR = \f(CW$hub\fR\->\fBipc()\fR" 4
+.IX Item "$ipc = $hub->ipc()"
+Get the IPC object used by the hub.
+.ie n .IP $hub\->set_no_ending($bool) 4
+.el .IP \f(CW$hub\fR\->set_no_ending($bool) 4
+.IX Item "$hub->set_no_ending($bool)"
+.PD 0
+.ie n .IP "$bool = $hub\->no_ending" 4
+.el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->no_ending" 4
+.IX Item "$bool = $hub->no_ending"
+.PD
+This can be used to disable auto-ending behavior for a hub. The auto-ending
+behavior is triggered by an end block and is used to cull IPC events, and
+output the final plan if the plan was 'NO PLAN'.
+.ie n .IP "$bool = $hub\->active" 4
+.el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->active" 4
+.IX Item "$bool = $hub->active"
+.PD 0
+.ie n .IP $hub\->set_active($bool) 4
+.el .IP \f(CW$hub\fR\->set_active($bool) 4
+.IX Item "$hub->set_active($bool)"
+.PD
+These are used to get/set the 'active' attribute. When true this attribute will
+force \f(CW\*(C`hub\->finalize()\*(C'\fR to take action even if there is no plan, and no
+tests have been run. This flag is useful for plugins that add follow-up
+behaviors that need to run even if no events are seen.
+.SS "STATE METHODS"
+.IX Subsection "STATE METHODS"
+.ie n .IP $hub\->\fBreset_state()\fR 4
+.el .IP \f(CW$hub\fR\->\fBreset_state()\fR 4
+.IX Item "$hub->reset_state()"
+Reset all state to the start. This sets the test count to 0, clears the plan,
+removes the failures, etc.
+.ie n .IP "$num = $hub\->count" 4
+.el .IP "\f(CW$num\fR = \f(CW$hub\fR\->count" 4
+.IX Item "$num = $hub->count"
+Get the number of tests that have been run.
+.ie n .IP "$num = $hub\->failed" 4
+.el .IP "\f(CW$num\fR = \f(CW$hub\fR\->failed" 4
+.IX Item "$num = $hub->failed"
+Get the number of failures (Not all failures come from a test fail, so this
+number can be larger than the count).
+.ie n .IP "$bool = $hub\->ended" 4
+.el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->ended" 4
+.IX Item "$bool = $hub->ended"
+True if the testing has ended. This MAY return the stack frame of the tool that
+ended the test, but that is not guaranteed.
+.ie n .IP "$bool = $hub\->is_passing" 4
+.el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->is_passing" 4
+.IX Item "$bool = $hub->is_passing"
+.PD 0
+.ie n .IP $hub\->is_passing($bool) 4
+.el .IP \f(CW$hub\fR\->is_passing($bool) 4
+.IX Item "$hub->is_passing($bool)"
+.PD
+Check if the overall test run is a failure. Can also be used to set the
+pass/fail status.
+.ie n .IP $hub\->plan($plan) 4
+.el .IP \f(CW$hub\fR\->plan($plan) 4
+.IX Item "$hub->plan($plan)"
+.PD 0
+.ie n .IP "$plan = $hub\->plan" 4
+.el .IP "\f(CW$plan\fR = \f(CW$hub\fR\->plan" 4
+.IX Item "$plan = $hub->plan"
+.PD
+Get or set the plan. The plan must be an integer larger than 0, the string
+\&'NO PLAN', or the string 'SKIP'.
+.ie n .IP "$bool = $hub\->check_plan" 4
+.el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->check_plan" 4
+.IX Item "$bool = $hub->check_plan"
+Check if the plan and counts match, but only if the tests have ended. If tests
+have not ended this will return undef, otherwise it will be a true/false.
+.SH "THIRD PARTY META-DATA"
+.IX Header "THIRD PARTY META-DATA"
+This object consumes Test2::Util::ExternalMeta which provides a consistent
+way for you to attach meta-data to instances of this class. This is useful for
+tools, plugins, and other extensions.
+.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
generated by cgit v1.2.3 (git 2.39.1) at 2025-02-16 02:52:56 +0000