1Test2::Hub(3)         User Contributed Perl Documentation        Test2::Hub(3)
2
3
4

NAME

6       Test2::Hub - The conduit through which all events flow.
7

SYNOPSIS

9           use Test2::Hub;
10
11           my $hub = Test2::Hub->new();
12           $hub->send(...);
13

DESCRIPTION

15       The hub is the place where all events get processed and handed off to
16       the formatter. The hub also tracks test state, and provides several
17       hooks into the event pipeline.
18

COMMON TASKS

20   SENDING EVENTS
21           $hub->send($event)
22
23       The "send()" method is used to issue an event to the hub. This method
24       will handle thread/fork sync, filters, listeners, TAP output, etc.
25
26   ALTERING OR REMOVING EVENTS
27       You can use either "filter()" or "pre_filter()", depending on your
28       needs. Both have identical syntax, so only "filter()" is shown here.
29
30           $hub->filter(sub {
31               my ($hub, $event) = @_;
32
33               my $action = get_action($event);
34
35               # No action should be taken
36               return $event if $action eq 'none';
37
38               # You want your filter to remove the event
39               return undef if $action eq 'delete';
40
41               if ($action eq 'do_it') {
42                   my $new_event = copy_event($event);
43                   ... Change your copy of the event ...
44                   return $new_event;
45               }
46
47               die "Should not happen";
48           });
49
50       By default, filters are not inherited by child hubs. That means if you
51       start a subtest, the subtest will not inherit the filter. You can
52       change this behavior with the "inherit" parameter:
53
54           $hub->filter(sub { ... }, inherit => 1);
55
56   LISTENING FOR EVENTS
57           $hub->listen(sub {
58               my ($hub, $event, $number) = @_;
59
60               ... do whatever you want with the event ...
61
62               # return is ignored
63           });
64
65       By default listeners are not inherited by child hubs. That means if you
66       start a subtest, the subtest will not inherit the listener. You can
67       change this behavior with the "inherit" parameter:
68
69           $hub->listen(sub { ... }, inherit => 1);
70
71   POST-TEST BEHAVIORS
72           $hub->follow_up(sub {
73               my ($trace, $hub) = @_;
74
75               ... do whatever you need to ...
76
77               # Return is ignored
78           });
79
80       follow_up subs are called only once, either when done_testing is
81       called, or in an END block.
82
83   SETTING THE FORMATTER
84       By default an instance of Test2::Formatter::TAP is created and used.
85
86           my $old = $hub->format(My::Formatter->new);
87
88       Setting the formatter will REPLACE any existing formatter. You may set
89       the formatter to undef to prevent output. The old formatter will be
90       returned if one was already set. Only one formatter is allowed at a
91       time.
92

METHODS

94       $hub->send($event)
95           This is where all events enter the hub for processing.
96
97       $hub->process($event)
98           This is called by send after it does any IPC handling. You can use
99           this to bypass the IPC process, but in general you should avoid
100           using this.
101
102       $old = $hub->format($formatter)
103           Replace the existing formatter instance with a new one. Formatters
104           must be objects that implement a "$formatter->write($event)"
105           method.
106
107       $sub = $hub->listen(sub { ... }, %optional_params)
108           You can use this to record all events AFTER they have been sent to
109           the formatter. No changes made here will be meaningful, except
110           possibly to other listeners.
111
112               $hub->listen(sub {
113                   my ($hub, $event, $number) = @_;
114
115                   ... do whatever you want with the event ...
116
117                   # return is ignored
118               });
119
120           Normally listeners are not inherited by child hubs such as
121           subtests. You can add the "inherit => 1" parameter to allow a
122           listener to be inherited.
123
124       $hub->unlisten($sub)
125           You can use this to remove a listen callback. You must pass in the
126           coderef returned by the "listen()" method.
127
128       $sub = $hub->filter(sub { ... }, %optional_params)
129       $sub = $hub->pre_filter(sub { ... }, %optional_params)
130           These can be used to add filters. Filters can modify, replace, or
131           remove events before anything else can see them.
132
133               $hub->filter(
134                   sub {
135                       my ($hub, $event) = @_;
136
137                       return $event;    # No Changes
138                       return;           # Remove the event
139
140                       # Or you can modify an event before returning it.
141                       $event->modify;
142                       return $event;
143                   }
144               );
145
146           If you are not using threads, forking, or IPC then the only
147           difference between a "filter" and a "pre_filter" is that
148           "pre_filter" subs run first. When you are using threads, forking,
149           or IPC, pre_filters happen to events before they are sent to their
150           destination proc/thread, ordinary filters happen only in the
151           destination hub/thread.
152
153           You cannot add a regular filter to a hub if the hub was created in
154           another process or thread. You can always add a pre_filter.
155
156       $hub->unfilter($sub)
157       $hub->pre_unfilter($sub)
158           These can be used to remove filters and pre_filters. The $sub
159           argument is the reference returned by "filter()" or "pre_filter()".
160
161       $hub->follow_op(sub { ... })
162           Use this to add behaviors that are called just before the hub is
163           finalized. The only argument to your codeblock will be a
164           Test2::EventFacet::Trace instance.
165
166               $hub->follow_up(sub {
167                   my ($trace, $hub) = @_;
168
169                   ... do whatever you need to ...
170
171                   # Return is ignored
172               });
173
174           follow_up subs are called only once, ether when done_testing is
175           called, or in an END block.
176
177       $sub = $hub->add_context_acquire(sub { ... });
178           Add a callback that will be called every time someone tries to
179           acquire a context. It gets a single argument, a reference of the
180           hash of parameters being used the construct the context. This is
181           your chance to change the parameters by directly altering the hash.
182
183               test2_add_callback_context_acquire(sub {
184                   my $params = shift;
185                   $params->{level}++;
186               });
187
188           This is a very scary API function. Please do not use this unless
189           you need to.  This is here for Test::Builder and backwards
190           compatibility. This has you directly manipulate the hash instead of
191           returning a new one for performance reasons.
192
193           Note Using this hook could have a huge performance impact.
194
195           The coderef you provide is returned and can be used to remove the
196           hook later.
197
198       $hub->remove_context_acquire($sub);
199           This can be used to remove a context acquire hook.
200
201       $sub = $hub->add_context_init(sub { ... });
202           This allows you to add callbacks that will trigger every time a new
203           context is created for the hub. The only argument to the sub will
204           be the Test2::API::Context instance that was created.
205
206           Note Using this hook could have a huge performance impact.
207
208           The coderef you provide is returned and can be used to remove the
209           hook later.
210
211       $hub->remove_context_init($sub);
212           This can be used to remove a context init hook.
213
214       $sub = $hub->add_context_release(sub { ... });
215           This allows you to add callbacks that will trigger every time a
216           context for this hub is released. The only argument to the sub will
217           be the Test2::API::Context instance that was released. These will
218           run in reverse order.
219
220           Note Using this hook could have a huge performance impact.
221
222           The coderef you provide is returned and can be used to remove the
223           hook later.
224
225       $hub->remove_context_release($sub);
226           This can be used to remove a context release hook.
227
228       $hub->cull()
229           Cull any IPC events (and process them).
230
231       $pid = $hub->pid()
232           Get the process id under which the hub was created.
233
234       $tid = $hub->tid()
235           Get the thread id under which the hub was created.
236
237       $hud = $hub->hid()
238           Get the identifier string of the hub.
239
240       $uuid = $hub->uuid()
241           If UUID tagging is enabled (see Test2::API) then the hub will have
242           a UUID.
243
244       $ipc = $hub->ipc()
245           Get the IPC object used by the hub.
246
247       $hub->set_no_ending($bool)
248       $bool = $hub->no_ending
249           This can be used to disable auto-ending behavior for a hub. The
250           auto-ending behavior is triggered by an end block and is used to
251           cull IPC events, and output the final plan if the plan was 'NO
252           PLAN'.
253
254       $bool = $hub->active
255       $hub->set_active($bool)
256           These are used to get/set the 'active' attribute. When true this
257           attribute will force "hub->finalize()" to take action even if there
258           is no plan, and no tests have been run. This flag is useful for
259           plugins that add follow-up behaviors that need to run even if no
260           events are seen.
261
262   STATE METHODS
263       $hub->reset_state()
264           Reset all state to the start. This sets the test count to 0, clears
265           the plan, removes the failures, etc.
266
267       $num = $hub->count
268           Get the number of tests that have been run.
269
270       $num = $hub->failed
271           Get the number of failures (Not all failures come from a test fail,
272           so this number can be larger than the count).
273
274       $bool = $hub->ended
275           True if the testing has ended. This MAY return the stack frame of
276           the tool that ended the test, but that is not guaranteed.
277
278       $bool = $hub->is_passing
279       $hub->is_passing($bool)
280           Check if the overall test run is a failure. Can also be used to set
281           the pass/fail status.
282
283       $hub->plan($plan)
284       $plan = $hub->plan
285           Get or set the plan. The plan must be an integer larger than 0, the
286           string 'NO PLAN', or the string 'SKIP'.
287
288       $bool = $hub->check_plan
289           Check if the plan and counts match, but only if the tests have
290           ended. If tests have not ended this will return undef, otherwise it
291           will be a true/false.
292

THIRD PARTY META-DATA

294       This object consumes Test2::Util::ExternalMeta which provides a
295       consistent way for you to attach meta-data to instances of this class.
296       This is useful for tools, plugins, and other extensions.
297

SOURCE

299       The source code repository for Test2 can be found at
300       http://github.com/Test-More/test-more/.
301

MAINTAINERS

303       Chad Granum <exodist@cpan.org>
304

AUTHORS

306       Chad Granum <exodist@cpan.org>
307
309       Copyright 2020 Chad Granum <exodist@cpan.org>.
310
311       This program is free software; you can redistribute it and/or modify it
312       under the same terms as Perl itself.
313
314       See http://dev.perl.org/licenses/
315
316
317
318perl v5.32.1                      2021-01-27                     Test2::Hub(3)
Impressum