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

NAME

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

DEPRECATED

9       This distribution is deprecated in favor of Test2, Test2::Suite, and
10       Test2::Workflow.
11
12       See Test::Stream::Manual::ToTest2 for a conversion guide.
13

SYNOPSIS

15           use Test::Stream::Hub;
16
17           my $hub = Test::Stream::Hub->new();
18           $hub->send(...);
19

DESCRIPTION

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

COMMON TASKS

26   SENDING EVENTS
27           $hub->send($event)
28
29       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
32   ALTERING OR REMOVING EVENTS
33           $hub->filter(sub {
34               my ($hub, $event) = @_;
35
36               my $action = get_action($event);
37
38               # No action should be taken
39               return $event if $action eq 'none';
40
41               # You want your filter to remove the event
42               return undef if $action eq 'delete';
43
44               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
50               die "Should not happen";
51           });
52
53       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
57           $hub->filter(sub { ... }, inherit => 1);
58
59   LISTENING FOR EVENTS
60           $hub->listen(sub {
61               my ($hub, $event, $number) = @_;
62
63               ... do whatever you want with the event ...
64
65               # return is ignored
66           });
67
68       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
72           $hub->listen(sub { ... }, inherit => 1);
73
74   POST-TEST BEHAVIORS
75           $hub->follow_up(sub {
76               my ($dbg, $hub) = @_;
77
78               ... do whatever you need to ...
79
80               # Return is ignored
81           });
82
83       follow_up subs are called only once, ether when done_testing is called,
84       or in an END block.
85
86   SETTING THE FORMATTER
87       By default an instance of Test::Stream::Formatter::TAP is created and
88       used.
89
90           my $old = $hub->format(My::Formatter->new);
91
92       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

METHODS

97       $hub->send($event)
98           This is where all events enter the hub for processing.
99
100       $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
105       $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
111           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
115           Recommended usage:
116
117               my $meta = $hub->meta(__PACKAGE__, {});
118               unless ($meta->{foo}) {
119                   $meta->{foo} = 1;
120                   $meta->{bar} = 2;
121               }
122
123       $val = $hub->delete_meta($key)
124           This will delete all data in the specified metadata key.
125
126       $val = $hub->get_meta($key)
127           This method will retrieve the value of any meta-data key specified.
128
129       $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
134       $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
138               {
139                   my $todo = $hub->set_todo("Broken");
140
141                   # These ok events will be TODO
142                   ok($foo->doit, "do it!");
143                   ok($foo->doit, "do it again!");
144
145                   # The todo setting goes away at the end of this scope.
146               }
147
148               # This result will not be TODO.
149               ok(1, "pass");
150
151           You can also do it without the indentation:
152
153               my $todo = $hub->set_todo("Broken");
154
155               # These ok events will be TODO
156               ok($foo->doit, "do it!");
157               ok($foo->doit, "do it again!");
158
159               # Unset the todo
160               $todo = undef;
161
162               # This result will not be TODO.
163               ok(1, "pass");
164
165           This method can be called while TODO is already in effect and it
166           will work in a sane way:
167
168               {
169                   my $first_todo = $hub->set_todo("Will fix soon");
170
171                   ok(0, "Not fixed"); # TODO: Will fix soon
172
173                   {
174                       my $second_todo = $hub->set_todo("Will fix eventually");
175                       ok(0, "Not fixed"); # TODO: Will fix eventually
176                   }
177
178                   ok(0, "Not fixed"); # TODO: Will fix soon
179               }
180
181           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
184       $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
189       $sub = $hub->munge(sub { ... })
190       $sub = $hub->munge(sub { ... }, inherit => 1)
191           *** DEPRECATED *** This will be removed in the near future.
192
193           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
198               $hub->munge(sub {
199                   my ($hub, $event) = @_;
200
201                   ... Modify the event object ...
202
203                   # return is ignored.
204               });
205
206           You can also completely remove the event from the stream:
207
208               $hub->munge(sub {
209                   my ($hub, $event) = @_;
210                   return unless ...;
211
212                   $_[1] = undef;
213               });
214
215           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
219       $hub->unmunge($sub)
220           *** DEPRECATED *** This will be removed in the near future.
221
222           You can use this to remove a munge callback. You must pass in the
223           coderef returned by the munge() method.
224
225       $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
230               $hub->listen(sub {
231                   my ($hub, $event, $number) = @_;
232
233                   ... do whatever you want with the event ...
234
235                   # return is ignored
236               });
237
238           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
242       $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
246       $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
251               $hub->follow_up(sub {
252                   my ($dbg, $hub) = @_;
253
254                   ... do whatever you need to ...
255
256                   # Return is ignored
257               });
258
259           follow_up subs are called only once, ether when done_testing is
260           called, or in an END block.
261
262       $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
267           Note Using this hook could have a huge performance impact.
268
269           The coderef you provide is returned and can be used to remove the
270           hook later.
271
272       $hub->remove_context_init($sub);
273           This can be used to remove a context init hook.
274
275       $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
281           Note Using this hook could have a huge performance impact.
282
283           The coderef you provide is returned and can be used to remove the
284           hook later.
285
286       $hub->remove_context_release($sub);
287           This can be used to remove a context release hook.
288
289       $hub->cull()
290           Cull any IPC events (and process them).
291
292       $pid = $hub->pid()
293           Get the process id under which the hub was created.
294
295       $tid = $hub->tid()
296           Get the thread id under which the hub was created.
297
298       $hud = $hub->hid()
299           Get the identifier string of the hub.
300
301       $ipc = $hub->ipc()
302           Get the IPC object used by the hub.
303
304       $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
311       $bool = $hub->parent_todo
312           This will be true if this hub is a child hub who's parent had todo
313           set.
314

SOURCE

316       The source code repository for Test::Stream can be found at
317       http://github.com/Test-More/Test-Stream/.
318

MAINTAINERS

320       Chad Granum <exodist@cpan.org>
321

AUTHORS

323       Chad Granum <exodist@cpan.org>
324
326       Copyright 2015 Chad Granum <exodist7@gmail.com>.
327
328       This program is free software; you can redistribute it and/or modify it
329       under the same terms as Perl itself.
330
331       See http://dev.perl.org/licenses/
332
333
334
335perl v5.36.0                      2023-01-20              Test::Stream::Hub(3)
Impressum