1Test2::Hub(3) User Contributed Perl Documentation Test2::Hub(3)
2
6 Test2::Hub - The conduit through which all events flow.
7
9 use Test2::Hub;
10 my $hub = Test2::Hub->new();
12 $hub->send(...);
13
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
20 SENDING EVENTS
21 $hub->send($event)
22 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 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 $hub->filter(sub {
31 my ($hub, $event) = @_;
32 my $action = get_action($event);
34 # No action should be taken
36 return $event if $action eq 'none';
37 # You want your filter to remove the event
39 return undef if $action eq 'delete';
40 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 die "Should not happen";
48 });
49 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 $hub->filter(sub { ... }, inherit => 1);
55 LISTENING FOR EVENTS
57 $hub->listen(sub {
58 my ($hub, $event, $number) = @_;
59 ... do whatever you want with the event ...
61 # return is ignored
63 });
64 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 $hub->listen(sub { ... }, inherit => 1);
70 POST-TEST BEHAVIORS
72 $hub->follow_up(sub {
73 my ($trace, $hub) = @_;
74 ... do whatever you need to ...
76 # Return is ignored
78 });
79 follow_up subs are called only once, either when done_testing is
81 called, or in an END block.
82 SETTING THE FORMATTER
84 By default an instance of Test2::Formatter::TAP is created and used.
85 my $old = $hub->format(My::Formatter->new);
87 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
94 $hub->send($event)
95 This is where all events enter the hub for processing.
96 $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 $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 $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 $hub->listen(sub {
113 my ($hub, $event, $number) = @_;
114 ... do whatever you want with the event ...
116 # return is ignored
118 });
119 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 $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 $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 $hub->filter(
134 sub {
135 my ($hub, $event) = @_;
136 return $event; # No Changes
138 return; # Remove the event
139 # Or you can modify an event before returning it.
141 $event->modify;
142 return $event;
143 }
144 );
145 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 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 $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 $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 $hub->follow_up(sub {
167 my ($trace, $hub) = @_;
168 ... do whatever you need to ...
170 # Return is ignored
172 });
173 follow_up subs are called only once, ether when done_testing is
175 called, or in an END block.
176 $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 test2_add_callback_context_acquire(sub {
184 my $params = shift;
185 $params->{level}++;
186 });
187 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 Note Using this hook could have a huge performance impact.
194 The coderef you provide is returned and can be used to remove the
196 hook later.
197 $hub->remove_context_acquire($sub);
199 This can be used to remove a context acquire hook.
200 $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 Note Using this hook could have a huge performance impact.
207 The coderef you provide is returned and can be used to remove the
209 hook later.
210 $hub->remove_context_init($sub);
212 This can be used to remove a context init hook.
213 $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 Note Using this hook could have a huge performance impact.
221 The coderef you provide is returned and can be used to remove the
223 hook later.
224 $hub->remove_context_release($sub);
226 This can be used to remove a context release hook.
227 $hub->cull()
229 Cull any IPC events (and process them).
230 $pid = $hub->pid()
232 Get the process id under which the hub was created.
233 $tid = $hub->tid()
235 Get the thread id under which the hub was created.
236 $hud = $hub->hid()
238 Get the identifier string of the hub.
239 $uuid = $hub->uuid()
241 If UUID tagging is enabled (see Test2::API) then the hub will have
242 a UUID.
243 $ipc = $hub->ipc()
245 Get the IPC object used by the hub.
246 $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 $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 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 $num = $hub->count
268 Get the number of tests that have been run.
269 $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 $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 $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 $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 $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
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
299 The source code repository for Test2 can be found at
300 http://github.com/Test-More/test-more/.
301
303 Chad Granum <exodist@cpan.org>
304
306 Chad Granum <exodist@cpan.org>
307
309 Copyright 2020 Chad Granum <exodist@cpan.org>.
310 This program is free software; you can redistribute it and/or modify it
312 under the same terms as Perl itself.
313 See http://dev.perl.org/licenses/
315perl v5.34.0 2022-03-05 Test2::Hub(3)