1Test::Stream::Hub(3) User Contributed Perl Documentation Test::Stream::Hub(3)
2
6 Test::Stream::Hub - The conduit through which all events flow.
7
9 This distribution is deprecated in favor of Test2, Test2::Suite, and
10 Test2::Workflow.
11 See Test::Stream::Manual::ToTest2 for a conversion guide.
13
15 use Test::Stream::Hub;
16 my $hub = Test::Stream::Hub->new();
18 $hub->send(...);
19
21 The hub is the place where all events get processed and handed off to
22 the formatter. The hub also tracks test state, and provides everal
23 hooks into the event pipeline.
24
26 SENDING EVENTS
27 $hub->send($event)
28 The "send()" method is used to issue an event to the hub. This method
30 will handle thread/fork sync, mungers, listeners, TAP output, etc.
31 ALTERING OR REMOVING EVENTS
33 $hub->filter(sub {
34 my ($hub, $event) = @_;
35 my $action = get_action($event);
37 # No action should be taken
39 return $event if $action eq 'none';
40 # You want your filter to remove the event
42 return undef if $action eq 'delete';
43 if ($action eq 'do_it') {
45 my $new_event = copy_event($event);
46 ... Change your copy of the event ...
47 return $new_event;
48 }
49 die "Should not happen";
51 });
52 By default filters are not inherited by child hubs, that means if you
54 start a subtest, the subtest will not inherit the filter. You can
55 change this behavior with the "inherit" parameter:
56 $hub->filter(sub { ... }, inherit => 1);
58 LISTENING FOR EVENTS
60 $hub->listen(sub {
61 my ($hub, $event, $number) = @_;
62 ... do whatever you want with the event ...
64 # return is ignored
66 });
67 By default listeners are not inherited by child hubs, that means if you
69 start a subtest, the subtest will not inherit the listener. You can
70 change this behavior with the "inherit" parameter:
71 $hub->listen(sub { ... }, inherit => 1);
73 POST-TEST BEHAVIORS
75 $hub->follow_up(sub {
76 my ($dbg, $hub) = @_;
77 ... do whatever you need to ...
79 # Return is ignored
81 });
82 follow_up subs are called only once, ether when done_testing is called,
84 or in an END block.
85 SETTING THE FORMATTER
87 By default an instance of Test::Stream::Formatter::TAP is created and
88 used.
89 my $old = $hub->format(My::Formatter->new);
91 Setting the formatter will REPLACE any existing formatter. You may set
93 the formatter to undef to prevent output. The old formatter will be
94 returned if one was already set. Only 1 formatter is allowed at a time.
95
97 $hub->send($event)
98 This is where all events enter the hub for processing.
99 $hub->process($event)
101 This is called by send after it does any IPC handling. You can use
102 this to bypass the IPC process, but in general you should avoid
103 using this.
104 $val = $hub->meta($key)
106 $val = $hub->meta($key, $default)
107 This method is made available to allow third party plugins to
108 associate meta-data with a hub. It is recommended that all third
109 party plugins use their module namespace as their meta-data key.
110 This method always returns the value for the key. If there is no
112 value it will be initialized to $default, in which case $default is
113 also returned.
114 Recommended usage:
116 my $meta = $hub->meta(__PACKAGE__, {});
118 unless ($meta->{foo}) {
119 $meta->{foo} = 1;
120 $meta->{bar} = 2;
121 }
122 $val = $hub->delete_meta($key)
124 This will delete all data in the specified metadata key.
125 $val = $hub->get_meta($key)
127 This method will retrieve the value of any meta-data key specified.
128 $string = $hub->get_todo()
130 Get the current TODO reason. This will be undef if there is no
131 active todo. Please note that 0 and '' (empty string) count as
132 active todo.
133 $ref = $hub->set_todo($reason)
135 This will set the todo message. The todo will remain in effect
136 until you let go of the reference returned by this method.
137 {
139 my $todo = $hub->set_todo("Broken");
140 # These ok events will be TODO
142 ok($foo->doit, "do it!");
143 ok($foo->doit, "do it again!");
144 # The todo setting goes away at the end of this scope.
146 }
147 # This result will not be TODO.
149 ok(1, "pass");
150 You can also do it without the indentation:
152 my $todo = $hub->set_todo("Broken");
154 # These ok events will be TODO
156 ok($foo->doit, "do it!");
157 ok($foo->doit, "do it again!");
158 # Unset the todo
160 $todo = undef;
161 # This result will not be TODO.
163 ok(1, "pass");
164 This method can be called while TODO is already in effect and it
166 will work in a sane way:
167 {
169 my $first_todo = $hub->set_todo("Will fix soon");
170 ok(0, "Not fixed"); # TODO: Will fix soon
172 {
174 my $second_todo = $hub->set_todo("Will fix eventually");
175 ok(0, "Not fixed"); # TODO: Will fix eventually
176 }
177 ok(0, "Not fixed"); # TODO: Will fix soon
179 }
180 This also works if you free todo's out of order. The most recently
182 set todo that is still active will always be used as the todo.
183 $old = $hub->format($formatter)
185 Replace the existing formatter instance with a new one. Formatters
186 must be objects that implement a "$formatter->write($event)"
187 method.
188 $sub = $hub->munge(sub { ... })
190 $sub = $hub->munge(sub { ... }, inherit => 1)
191 *** DEPRECATED *** This will be removed in the near future.
192 This adds your codeblock as a callback. Every event that hits this
194 hub will be given to your munger BEFORE it is sent to the
195 formatter. You can make any modifications you want to the event
196 object.
197 $hub->munge(sub {
199 my ($hub, $event) = @_;
200 ... Modify the event object ...
202 # return is ignored.
204 });
205 You can also completely remove the event from the stream:
207 $hub->munge(sub {
209 my ($hub, $event) = @_;
210 return unless ...;
211 $_[1] = undef;
213 });
214 Normally mungers are not inherited by child hubs such as subtests.
216 You can add the "inherit => 1" parameter to allow a munger to be
217 inherited.
218 $hub->unmunge($sub)
220 *** DEPRECATED *** This will be removed in the near future.
221 You can use this to remove a munge callback. You must pass in the
223 coderef returned by the "munge()" method.
224 $sub = $hub->listen(sub { ... })
226 You can use this to record all events AFTER they have been sent to
227 the formatter. No changes made here will be meaningful, except
228 possibly to other listeners.
229 $hub->listen(sub {
231 my ($hub, $event, $number) = @_;
232 ... do whatever you want with the event ...
234 # return is ignored
236 });
237 Normally listeners are not inherited by child hubs such as
239 subtests. You can add the "inherit => 1" parameter to allow a
240 listener to be inherited.
241 $hub->unlisten($sub)
243 You can use this to remove a listen callback. You must pass in the
244 coderef returned by the "listen()" method.
245 $hub->follow_op(sub { ... })
247 Use this to add behaviors that are called just before the
248 Test::Stream::State for the hub is finalized. The only argument to
249 your codeblock will be a Test::Stream::DebugInfo instance.
250 $hub->follow_up(sub {
252 my ($dbg, $hub) = @_;
253 ... do whatever you need to ...
255 # Return is ignored
257 });
258 follow_up subs are called only once, ether when done_testing is
260 called, or in an END block.
261 $sub = $hub->add_context_init(sub { ... });
263 This allows you to add callbacks that will trigger every time a new
264 context is created for the hub. The only argument to the sub will
265 be the Test::Stream::Context instance that was created.
266 Note Using this hook could have a huge performance impact.
268 The coderef you provide is returned and can be used to remove the
270 hook later.
271 $hub->remove_context_init($sub);
273 This can be used to remove a context init hook.
274 $sub = $hub->add_context_release(sub { ... });
276 This allows you to add callbacks that will trigger every time a
277 context for this hub is released. The only argument to the sub will
278 be the Test::Stream::Context instance that was released. These will
279 run in reverse order.
280 Note Using this hook could have a huge performance impact.
282 The coderef you provide is returned and can be used to remove the
284 hook later.
285 $hub->remove_context_release($sub);
287 This can be used to remove a context release hook.
288 $hub->cull()
290 Cull any IPC events (and process them).
291 $pid = $hub->pid()
293 Get the process id under which the hub was created.
294 $tid = $hub->tid()
296 Get the thread id under which the hub was created.
297 $hud = $hub->hid()
299 Get the identifier string of the hub.
300 $ipc = $hub->ipc()
302 Get the IPC object used by the hub.
303 $hub->set_no_ending($bool)
305 $bool = $hub->no_ending
306 This can be used to disable auto-ending behavior for a hub. The
307 auto-ending behavior is triggered by an end block and is used to
308 cull IPC events, and output the final plan if the plan was
309 'no_plan'.
310 $bool = $hub->parent_todo
312 This will be true if this hub is a child hub who's parent had todo
313 set.
314
316 The source code repository for Test::Stream can be found at
317 http://github.com/Test-More/Test-Stream/.
318
320 Chad Granum <exodist@cpan.org>
321
323 Chad Granum <exodist@cpan.org>
324
326 Copyright 2015 Chad Granum <exodist7@gmail.com>.
327 This program is free software; you can redistribute it and/or modify it
329 under the same terms as Perl itself.
330 See http://dev.perl.org/licenses/
332perl v5.36.0 2022-07-22 Test::Stream::Hub(3)