Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Hub.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Hub 3pm"
61 .TH Test2::Hub 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Hub \- The conduit through which all events flow.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Test2::Hub;
72 \&
73 \& my $hub = Test2::Hub\->new();
74 \& $hub\->send(...);
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 The hub is the place where all events get processed and handed off to the
79 formatter. The hub also tracks test state, and provides several hooks into the
80 event pipeline.
81 .SH "COMMON TASKS"
82 .IX Header "COMMON TASKS"
83 .SS "SENDING EVENTS"
84 .IX Subsection "SENDING EVENTS"
85 .Vb 1
86 \& $hub\->send($event)
87 .Ve
88 .PP
89 The \f(CWsend()\fR method is used to issue an event to the hub. This method will
90 handle thread/fork sync, filters, listeners, TAP output, etc.
91 .SS "ALTERING OR REMOVING EVENTS"
92 .IX Subsection "ALTERING OR REMOVING EVENTS"
93 You can use either \f(CWfilter()\fR or \f(CWpre_filter()\fR, depending on your
94 needs. Both have identical syntax, so only \f(CWfilter()\fR is shown here.
95 .PP
96 .Vb 2
97 \& $hub\->filter(sub {
98 \& my ($hub, $event) = @_;
99 \&
100 \& my $action = get_action($event);
101 \&
102 \& # No action should be taken
103 \& return $event if $action eq \*(Aqnone\*(Aq;
104 \&
105 \& # You want your filter to remove the event
106 \& return undef if $action eq \*(Aqdelete\*(Aq;
107 \&
108 \& if ($action eq \*(Aqdo_it\*(Aq) {
109 \& my $new_event = copy_event($event);
110 \& ... Change your copy of the event ...
111 \& return $new_event;
112 \& }
113 \&
114 \& die "Should not happen";
115 \& });
116 .Ve
117 .PP
118 By default, filters are not inherited by child hubs. That means if you start a
119 subtest, the subtest will not inherit the filter. You can change this behavior
120 with the \f(CW\*(C`inherit\*(C'\fR parameter:
121 .PP
122 .Vb 1
123 \& $hub\->filter(sub { ... }, inherit => 1);
124 .Ve
125 .SS "LISTENING FOR EVENTS"
126 .IX Subsection "LISTENING FOR EVENTS"
127 .Vb 2
128 \& $hub\->listen(sub {
129 \& my ($hub, $event, $number) = @_;
130 \&
131 \& ... do whatever you want with the event ...
132 \&
133 \& # return is ignored
134 \& });
135 .Ve
136 .PP
137 By default listeners are not inherited by child hubs. That means if you start a
138 subtest, the subtest will not inherit the listener. You can change this behavior
139 with the \f(CW\*(C`inherit\*(C'\fR parameter:
140 .PP
141 .Vb 1
142 \& $hub\->listen(sub { ... }, inherit => 1);
143 .Ve
144 .SS "POST\-TEST BEHAVIORS"
145 .IX Subsection "POST-TEST BEHAVIORS"
146 .Vb 2
147 \& $hub\->follow_up(sub {
148 \& my ($trace, $hub) = @_;
149 \&
150 \& ... do whatever you need to ...
151 \&
152 \& # Return is ignored
153 \& });
154 .Ve
155 .PP
156 follow_up subs are called only once, either when done_testing is called, or in
157 an END block.
158 .SS "SETTING THE FORMATTER"
159 .IX Subsection "SETTING THE FORMATTER"
160 By default an instance of Test2::Formatter::TAP is created and used.
161 .PP
162 .Vb 1
163 \& my $old = $hub\->format(My::Formatter\->new);
164 .Ve
165 .PP
166 Setting the formatter will REPLACE any existing formatter. You may set the
167 formatter to undef to prevent output. The old formatter will be returned if one
168 was already set. Only one formatter is allowed at a time.
169 .SH METHODS
170 .IX Header "METHODS"
171 .ie n .IP $hub\->send($event) 4
172 .el .IP \f(CW$hub\fR\->send($event) 4
173 .IX Item "$hub->send($event)"
174 This is where all events enter the hub for processing.
175 .ie n .IP $hub\->process($event) 4
176 .el .IP \f(CW$hub\fR\->process($event) 4
177 .IX Item "$hub->process($event)"
178 This is called by send after it does any IPC handling. You can use this to
179 bypass the IPC process, but in general you should avoid using this.
180 .ie n .IP "$old = $hub\->format($formatter)" 4
181 .el .IP "\f(CW$old\fR = \f(CW$hub\fR\->format($formatter)" 4
182 .IX Item "$old = $hub->format($formatter)"
183 Replace the existing formatter instance with a new one. Formatters must be
184 objects that implement a \f(CW\*(C`$formatter\->write($event)\*(C'\fR method.
185 .ie n .IP "$sub = $hub\->listen(sub { ... }, %optional_params)" 4
186 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->listen(sub { ... }, \f(CW%optional_params\fR)" 4
187 .IX Item "$sub = $hub->listen(sub { ... }, %optional_params)"
188 You can use this to record all events AFTER they have been sent to the
189 formatter. No changes made here will be meaningful, except possibly to other
190 listeners.
191 .Sp
192 .Vb 2
193 \& $hub\->listen(sub {
194 \& my ($hub, $event, $number) = @_;
195 \&
196 \& ... do whatever you want with the event ...
197 \&
198 \& # return is ignored
199 \& });
200 .Ve
201 .Sp
202 Normally listeners are not inherited by child hubs such as subtests. You can
203 add the \f(CW\*(C`inherit => 1\*(C'\fR parameter to allow a listener to be inherited.
204 .ie n .IP $hub\->unlisten($sub) 4
205 .el .IP \f(CW$hub\fR\->unlisten($sub) 4
206 .IX Item "$hub->unlisten($sub)"
207 You can use this to remove a listen callback. You must pass in the coderef
208 returned by the \f(CWlisten()\fR method.
209 .ie n .IP "$sub = $hub\->filter(sub { ... }, %optional_params)" 4
210 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->filter(sub { ... }, \f(CW%optional_params\fR)" 4
211 .IX Item "$sub = $hub->filter(sub { ... }, %optional_params)"
212 .PD 0
213 .ie n .IP "$sub = $hub\->pre_filter(sub { ... }, %optional_params)" 4
214 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->pre_filter(sub { ... }, \f(CW%optional_params\fR)" 4
215 .IX Item "$sub = $hub->pre_filter(sub { ... }, %optional_params)"
216 .PD
217 These can be used to add filters. Filters can modify, replace, or remove events
218 before anything else can see them.
219 .Sp
220 .Vb 3
221 \& $hub\->filter(
222 \& sub {
223 \& my ($hub, $event) = @_;
224 \&
225 \& return $event; # No Changes
226 \& return; # Remove the event
227 \&
228 \& # Or you can modify an event before returning it.
229 \& $event\->modify;
230 \& return $event;
231 \& }
232 \& );
233 .Ve
234 .Sp
235 If you are not using threads, forking, or IPC then the only difference between
236 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
237 are using threads, forking, or IPC, pre_filters happen to events before they
238 are sent to their destination proc/thread, ordinary filters happen only in the
239 destination hub/thread.
240 .Sp
241 You cannot add a regular filter to a hub if the hub was created in another
242 process or thread. You can always add a pre_filter.
243 .ie n .IP $hub\->unfilter($sub) 4
244 .el .IP \f(CW$hub\fR\->unfilter($sub) 4
245 .IX Item "$hub->unfilter($sub)"
246 .PD 0
247 .ie n .IP $hub\->pre_unfilter($sub) 4
248 .el .IP \f(CW$hub\fR\->pre_unfilter($sub) 4
249 .IX Item "$hub->pre_unfilter($sub)"
250 .PD
251 These can be used to remove filters and pre_filters. The \f(CW$sub\fR argument is
252 the reference returned by \f(CWfilter()\fR or \f(CWpre_filter()\fR.
253 .ie n .IP "$hub\->follow_op(sub { ... })" 4
254 .el .IP "\f(CW$hub\fR\->follow_op(sub { ... })" 4
255 .IX Item "$hub->follow_op(sub { ... })"
256 Use this to add behaviors that are called just before the hub is finalized. The
257 only argument to your codeblock will be a Test2::EventFacet::Trace instance.
258 .Sp
259 .Vb 2
260 \& $hub\->follow_up(sub {
261 \& my ($trace, $hub) = @_;
262 \&
263 \& ... do whatever you need to ...
264 \&
265 \& # Return is ignored
266 \& });
267 .Ve
268 .Sp
269 follow_up subs are called only once, ether when done_testing is called, or in
270 an END block.
271 .ie n .IP "$sub = $hub\->add_context_acquire(sub { ... });" 4
272 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_acquire(sub { ... });" 4
273 .IX Item "$sub = $hub->add_context_acquire(sub { ... });"
274 Add a callback that will be called every time someone tries to acquire a
275 context. It gets a single argument, a reference of the hash of parameters
276 being used the construct the context. This is your chance to change the
277 parameters by directly altering the hash.
278 .Sp
279 .Vb 4
280 \& test2_add_callback_context_acquire(sub {
281 \& my $params = shift;
282 \& $params\->{level}++;
283 \& });
284 .Ve
285 .Sp
286 This is a very scary API function. Please do not use this unless you need to.
287 This is here for Test::Builder and backwards compatibility. This has you
288 directly manipulate the hash instead of returning a new one for performance
289 reasons.
290 .Sp
291 \&\fBNote\fR Using this hook could have a huge performance impact.
292 .Sp
293 The coderef you provide is returned and can be used to remove the hook later.
294 .ie n .IP $hub\->remove_context_acquire($sub); 4
295 .el .IP \f(CW$hub\fR\->remove_context_acquire($sub); 4
296 .IX Item "$hub->remove_context_acquire($sub);"
297 This can be used to remove a context acquire hook.
298 .ie n .IP "$sub = $hub\->add_context_init(sub { ... });" 4
299 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_init(sub { ... });" 4
300 .IX Item "$sub = $hub->add_context_init(sub { ... });"
301 This allows you to add callbacks that will trigger every time a new context is
302 created for the hub. The only argument to the sub will be the
303 Test2::API::Context instance that was created.
304 .Sp
305 \&\fBNote\fR Using this hook could have a huge performance impact.
306 .Sp
307 The coderef you provide is returned and can be used to remove the hook later.
308 .ie n .IP $hub\->remove_context_init($sub); 4
309 .el .IP \f(CW$hub\fR\->remove_context_init($sub); 4
310 .IX Item "$hub->remove_context_init($sub);"
311 This can be used to remove a context init hook.
312 .ie n .IP "$sub = $hub\->add_context_release(sub { ... });" 4
313 .el .IP "\f(CW$sub\fR = \f(CW$hub\fR\->add_context_release(sub { ... });" 4
314 .IX Item "$sub = $hub->add_context_release(sub { ... });"
315 This allows you to add callbacks that will trigger every time a context for
316 this hub is released. The only argument to the sub will be the
317 Test2::API::Context instance that was released. These will run in reverse
318 order.
319 .Sp
320 \&\fBNote\fR Using this hook could have a huge performance impact.
321 .Sp
322 The coderef you provide is returned and can be used to remove the hook later.
323 .ie n .IP $hub\->remove_context_release($sub); 4
324 .el .IP \f(CW$hub\fR\->remove_context_release($sub); 4
325 .IX Item "$hub->remove_context_release($sub);"
326 This can be used to remove a context release hook.
327 .ie n .IP $hub\->\fBcull()\fR 4
328 .el .IP \f(CW$hub\fR\->\fBcull()\fR 4
329 .IX Item "$hub->cull()"
330 Cull any IPC events (and process them).
331 .ie n .IP "$pid = $hub\->\fBpid()\fR" 4
332 .el .IP "\f(CW$pid\fR = \f(CW$hub\fR\->\fBpid()\fR" 4
333 .IX Item "$pid = $hub->pid()"
334 Get the process id under which the hub was created.
335 .ie n .IP "$tid = $hub\->\fBtid()\fR" 4
336 .el .IP "\f(CW$tid\fR = \f(CW$hub\fR\->\fBtid()\fR" 4
337 .IX Item "$tid = $hub->tid()"
338 Get the thread id under which the hub was created.
339 .ie n .IP "$hud = $hub\->\fBhid()\fR" 4
340 .el .IP "\f(CW$hud\fR = \f(CW$hub\fR\->\fBhid()\fR" 4
341 .IX Item "$hud = $hub->hid()"
342 Get the identifier string of the hub.
343 .ie n .IP "$uuid = $hub\->\fBuuid()\fR" 4
344 .el .IP "\f(CW$uuid\fR = \f(CW$hub\fR\->\fBuuid()\fR" 4
345 .IX Item "$uuid = $hub->uuid()"
346 If UUID tagging is enabled (see Test2::API) then the hub will have a UUID.
347 .ie n .IP "$ipc = $hub\->\fBipc()\fR" 4
348 .el .IP "\f(CW$ipc\fR = \f(CW$hub\fR\->\fBipc()\fR" 4
349 .IX Item "$ipc = $hub->ipc()"
350 Get the IPC object used by the hub.
351 .ie n .IP $hub\->set_no_ending($bool) 4
352 .el .IP \f(CW$hub\fR\->set_no_ending($bool) 4
353 .IX Item "$hub->set_no_ending($bool)"
354 .PD 0
355 .ie n .IP "$bool = $hub\->no_ending" 4
356 .el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->no_ending" 4
357 .IX Item "$bool = $hub->no_ending"
358 .PD
359 This can be used to disable auto\-ending behavior for a hub. The auto\-ending
360 behavior is triggered by an end block and is used to cull IPC events, and
361 output the final plan if the plan was \*(AqNO PLAN\*(Aq.
362 .ie n .IP "$bool = $hub\->active" 4
363 .el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->active" 4
364 .IX Item "$bool = $hub->active"
365 .PD 0
366 .ie n .IP $hub\->set_active($bool) 4
367 .el .IP \f(CW$hub\fR\->set_active($bool) 4
368 .IX Item "$hub->set_active($bool)"
369 .PD
370 These are used to get/set the \*(Aqactive\*(Aq attribute. When true this attribute will
371 force \f(CW\*(C`hub\->finalize()\*(C'\fR to take action even if there is no plan, and no
372 tests have been run. This flag is useful for plugins that add follow\-up
373 behaviors that need to run even if no events are seen.
374 .SS "STATE METHODS"
375 .IX Subsection "STATE METHODS"
376 .ie n .IP $hub\->\fBreset_state()\fR 4
377 .el .IP \f(CW$hub\fR\->\fBreset_state()\fR 4
378 .IX Item "$hub->reset_state()"
379 Reset all state to the start. This sets the test count to 0, clears the plan,
380 removes the failures, etc.
381 .ie n .IP "$num = $hub\->count" 4
382 .el .IP "\f(CW$num\fR = \f(CW$hub\fR\->count" 4
383 .IX Item "$num = $hub->count"
384 Get the number of tests that have been run.
385 .ie n .IP "$num = $hub\->failed" 4
386 .el .IP "\f(CW$num\fR = \f(CW$hub\fR\->failed" 4
387 .IX Item "$num = $hub->failed"
388 Get the number of failures (Not all failures come from a test fail, so this
389 number can be larger than the count).
390 .ie n .IP "$bool = $hub\->ended" 4
391 .el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->ended" 4
392 .IX Item "$bool = $hub->ended"
393 True if the testing has ended. This MAY return the stack frame of the tool that
394 ended the test, but that is not guaranteed.
395 .ie n .IP "$bool = $hub\->is_passing" 4
396 .el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->is_passing" 4
397 .IX Item "$bool = $hub->is_passing"
398 .PD 0
399 .ie n .IP $hub\->is_passing($bool) 4
400 .el .IP \f(CW$hub\fR\->is_passing($bool) 4
401 .IX Item "$hub->is_passing($bool)"
402 .PD
403 Check if the overall test run is a failure. Can also be used to set the
404 pass/fail status.
405 .ie n .IP $hub\->plan($plan) 4
406 .el .IP \f(CW$hub\fR\->plan($plan) 4
407 .IX Item "$hub->plan($plan)"
408 .PD 0
409 .ie n .IP "$plan = $hub\->plan" 4
410 .el .IP "\f(CW$plan\fR = \f(CW$hub\fR\->plan" 4
411 .IX Item "$plan = $hub->plan"
412 .PD
413 Get or set the plan. The plan must be an integer larger than 0, the string
414 \&\*(AqNO PLAN\*(Aq, or the string \*(AqSKIP\*(Aq.
415 .ie n .IP "$bool = $hub\->check_plan" 4
416 .el .IP "\f(CW$bool\fR = \f(CW$hub\fR\->check_plan" 4
417 .IX Item "$bool = $hub->check_plan"
418 Check if the plan and counts match, but only if the tests have ended. If tests
419 have not ended this will return undef, otherwise it will be a true/false.
420 .SH "THIRD PARTY META\-DATA"
421 .IX Header "THIRD PARTY META-DATA"
422 This object consumes Test2::Util::ExternalMeta which provides a consistent
423 way for you to attach meta\-data to instances of this class. This is useful for
424 tools, plugins, and other extensions.
425 .SH SOURCE
426 .IX Header "SOURCE"
427 The source code repository for Test2 can be found at
428 <https://github.com/Test\-More/test\-more/>.
429 .SH MAINTAINERS
430 .IX Header "MAINTAINERS"
431 .IP "Chad Granum <[email protected]>" 4
432 .IX Item "Chad Granum <[email protected]>"
433 .SH AUTHORS
434 .IX Header "AUTHORS"
435 .IP "Chad Granum <[email protected]>" 4
436 .IX Item "Chad Granum <[email protected]>"
437 .SH COPYRIGHT
438 .IX Header "COPYRIGHT"
439 Copyright Chad Granum <[email protected]>.
440 .PP
441 This program is free software; you can redistribute it and/or
442 modify it under the same terms as Perl itself.
443 .PP
444 See <https://dev.perl.org/licenses/>