1Test::Stream::Context(3U)ser Contributed Perl DocumentatiToenst::Stream::Context(3)
2
6 Test::Stream::Context - Object to represent a testing context.
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 The context object is the primary interface for authors of testing
16 tools written with Test::Stream. The context object represents the
17 context in which a test takes place (File and Line Number), and
18 provides a quick way to generate events from that context. The context
19 object also takes care of sending events to the correct
20 Test::Stream::Hub instance.
21
23 use Test::Stream::Context qw/context release/;
24 sub my_ok {
26 my ($bool, $name) = @_;
27 my $ctx = context();
28 $ctx->ok($bool, $name);
29 $ctx->release; # You MUST do this!
30 return $bool;
31 }
32 Context objects make it easy to wrap other tools that also use context.
34 Once you grab a context, any tool you call before releasing your
35 context will inherit it:
36 sub wrapper {
38 my ($bool, $name) = @_;
39 my $ctx = context();
40 $ctx->diag("wrapping my_ok");
41 my $out = my_ok($bool, $name);
43 $ctx->release; # You MUST do this!
44 return $out;
45 }
46 Notice above that we are grabbing a return value, then releasing our
48 context, then returning the value. We can combine these last 3
49 statements into a single statement using the "release" function:
50 sub wrapper {
52 my ($bool, $name) = @_;
53 my $ctx = context();
54 $ctx->diag("wrapping my_ok");
55 # You must always release the context.
57 release $ctx, my_ok($bool, $name);
58 }
59
61 You MUST always release the context when done with it
62 Releasing the context tells the system you are done with it. This
63 gives it a chance to run any necessary callbacks or cleanup tasks.
64 If you forget to release the context it will be released for you
65 using a destructor, and it will give you a warning.
66 In general the destructor is not preferred because it does not
68 allow callbacks to run some types of code, for example you cannot
69 throw an exception from a destructor.
70 You MUST NOT pass context objects around
72 When you obtain a context object it is made specifically for your
73 tool and any tools nested within. If you pass a context around you
74 run the risk of polluting other tools with incorrect context
75 information.
76 If you are certain that you want a different tool to use the same
78 context you may pass it a snapshot. "$ctx->snapshot" will give you
79 a shallow clone of the context that is safe to pass around or
80 store.
81 You MUST NOT store or cache a context for later
83 As long as a context exists for a given hub, all tools that try to
84 get a context will get the existing instance. If you try to store
85 the context you will pollute other tools with incorrect context
86 information.
87 If you are certain that you want to save the context for later, you
89 can use a snapshot. "$ctx->snapshot" will give you a shallow clone
90 of the context that is safe to pass around or store.
91 context() has some mechanisms to protect you if you do cause a
93 context to persist beyond the scope in which it was obtained. In
94 practice you should not rely on these protections, and they are
95 fairly noisy with warnings.
96 You SHOULD obtain your context as soon as possible in a given tool
98 You never know what tools you call from within your own tool will
99 need a context. Obtaining the context early ensures that nested
100 tools can find the context you want them to find.
101
103 All exports are optional, you must specify subs to import. If you want
104 to import all subs use '-all'.
105 use Test::Stream::Context '-all';
107 context()
109 Usage:
110 $ctx = context()
112 $ctx = context(%params)
113 The context() function will always return the current context to you.
115 If there is already a context active it will be returned. If there is
116 not an active context one will be generated. When a context is
117 generated it will default to using the file and line number where the
118 currently running sub was called from.
119 Please see the "CRITICAL DETAILS" section for important rools about
121 what you can and acannot do with a context once it is obtained.
122 Note This function will throw an exception if you ignore the context
124 object it returns.
125 OPTIONAL PARAMETERS
127 All parameters to "context" are optional.
129 level => $int
131 If you must obtain a context in a sub deper than your entry point
132 you can use this to tell it how many EXTRA stack frames to look
133 back. If this option is not provided the default of 0 is used.
134 sub third_party_tool {
136 my $sub = shift;
137 ... # Does not obtain a context
138 $sub->();
139 ...
140 }
141 third_party_tool(sub {
143 my $ctx = context(level => 1);
144 ...
145 $ctx->release;
146 });
147 wrapped => $int
149 Use this if you need to write your own tool that wraps a call to
150 context() with the intent that it should return a context object.
151 sub my_context {
153 my %params = ( wrapped => 0, @_ );
154 $params{wrapped}++;
155 my $ctx = context(%params);
156 ...
157 return $ctx;
158 }
159 sub my_tool {
161 my $ctx = my_context();
162 ...
163 $ctx->release;
164 }
165 If you do not do this than tools you call that also check for a
167 context will notice that the context they grabbed was created at
168 the same stack depth, which will trigger protective measures that
169 warn you and destroy the existing context.
170 stack => $stack
172 Normally context() looks at the global hub stack initialized in
173 Test::Stream::Sync. If you are maintaining your own
174 Test::Stream::Stack instance you may pass it in to be used instead
175 of the global one.
176 hub => $hub
178 Use this parameter if you want to onbtain the context for a
179 specific hub instead of whatever one happens to be at the top of
180 the stack.
181 on_init => sub { ... }
183 This lets you provide a callback sub that will be called ONLY if
184 your call to c<context()> generated a new context. The callback
185 WILL NOT be called if context() is returning an existing context.
186 The only argument passed into the callback will be the context
187 object itself.
188 sub foo {
190 my $ctx = context(on_init => sub { 'will run' });
191 my $inner = sub {
193 # This callback is not run since we are getting the existing
194 # context from our parent sub.
195 my $ctx = context(on_init => sub { 'will NOT run' });
196 $ctx->release;
197 }
198 $inner->();
199 $ctx->release;
201 }
202 on_release => sub { ... }
204 This lets you provide a callback sub that will be called when the
205 context instance is released. This callback will be added to the
206 returned context even if an existing context is returned. If
207 multiple calls to context add callbacks then all will be called in
208 reverse order when the context is finally released.
209 sub foo {
211 my $ctx = context(on_release => sub { 'will run second' });
212 my $inner = sub {
214 my $ctx = context(on_release => sub { 'will run first' });
215 # Neither callback runs on this release
217 $ctx->release;
218 }
219 $inner->();
220 # Both callbacks run here.
222 $ctx->release;
223 }
224 release()
226 Usage:
227 release $ctx;
229 release $ctx, ...;
230 This is intended as a shortcut that lets you release your context and
232 return a value in one statement. This function will get your context,
233 and any other arguments provided. It will release your context, then
234 return everything else. If you only provide one argument it will
235 return that one argument as a scalar. If you provide multiple
236 arguments it will return them all as a list.
237 sub scalar_tool {
239 my $ctx = context();
240 ...
241 return release $ctx, 1;
243 }
244 sub list_tool {
246 my $ctx = context();
247 ...
248 return release $ctx, qw/a b c/;
250 }
251 This tool is most useful when you want to return the value you get from
253 calling a function that needs to see the current context:
254 my $ctx = context();
256 my $out = some_tool(...);
257 $ctx->release;
258 return $out;
259 We can combine the last 3 lines of the above like so:
261 my $ctx = context();
263 release $ctx, some_tool(...);
264
266 CLASS METHODS
267 Test::Stream::Context->ON_INIT(sub { ... }, ...)
268 Test::Stream::Context->ON_RELEASE(sub { ... }, ...)
269 These are GLOBAL hooks into the context tools. Every sub added via
270 ON_INIT will be called every single time a new context is
271 initialized. Every sub added via ON_RELEASE will be called every
272 single time a context is released.
273 Subs will receive exactly 1 argument, that is the context itself.
275 You should not call "release" on the context within your callback.
276 INSTANCE METHODS
278 $clone = $ctx->snapshot()
279 This will return a shallow clone of the context. The shallow clone
280 is safe to store for later.
281 $ctx->release()
283 This will release the context. It will also set the $ctx variable
284 to "undef" (it works regardless of what you name the variable).
285 $ctx->throw($message)
287 This will throw an exception reporting to the file and line number
288 of the context. This will also release the context for you.
289 $ctx->alert($message)
291 This will issue a warning from the file and line number of the
292 context.
293 $stack = $ctx->stack()
295 This will return the Test::Stream::Stack instance the context used
296 to find the current hub.
297 $hub = $ctx->hub()
299 This will return the Test::Stream::Hub instance the context
300 recognises as the current one to which all events should be sent.
301 $dbg = $ctx->debug()
303 This will return the Test::Stream::DebugInfo instance used by the
304 context.
305 $ctx->do_in_context(\&code, @args);
307 Sometimes you have a context that is not current, and you want
308 things to use it as the current one. In these cases you can call
309 "$ctx->do_in_context(sub { ... })". The codeblock will be run, and
310 anything inside of it that looks for a context will find the one on
311 which the method was called.
312 This DOES NOT effect context on other hubs, only the hub used by
314 the context will be effected.
315 my $ctx = ...;
317 $ctx->do_in_context(sub {
318 my $ctx = context(); # returns the $ctx the sub is called on
319 });
320 EVENT PRODUCTION METHODS
322 $event = $ctx->ok($bool, $name)
323 $event = $ctx->ok($bool, $name, \@diag)
324 This will create an Test::Stream::Event::Ok object for you. The
325 diagnostics array will be used on the object in the event of a
326 failure, if the test passes the diagnostics will be ignored.
327 $event = $ctx->note($message)
329 Send an Test::Stream::Event::Note. This event prints a message to
330 STDOUT.
331 $event = $ctx->diag($message)
333 Send an Test::Stream::Event::Diag. This event prints a message to
334 STDERR.
335 $event = $ctx->plan($max)
337 $event = $ctx->plan(0, 'SKIP', $reason)
338 This can be used to send an Test::Stream::Event::Plan event. This
339 event usually takes either a number of tests you expect to run.
340 Optionally you can set the expected count to 0 and give the 'SKIP'
341 directive with a reason to cause all tests to be skipped.
342 $event = $ctx->bail($reason)
344 This sends an Test::Stream::Event::Bail event. This event will
345 completely terminate all testing.
346 $event = $ctx->send_event($Type, %parameters)
348 This lets you build and send an event of any type. The $Type
349 argument should be the event package name with
350 "Test::Stream::Event::" left off, or a fully qualified package name
351 prefixed with a '+'. The event is returned after it is sent.
352 my $event = $ctx->send_event('Ok', ...);
354 or
356 my $event = $ctx->send_event('+Test::Stream::Event::Ok', ...);
358 $event = $ctx->build_event($Type, %parameters)
360 This is the same as send_event(), except it builds and returns the
361 event without sending it.
362
364 There are 2 types of hooks, init hooks, and release hooks. As the names
365 suggest, these hooks are triggered when contexts are created or
366 released.
367 INIT HOOKS
369 These are called whenever a context is initialized. That means when a
370 new instance is created. These hooks are NOT called every time
371 something requests a context, just when a new one is created.
372 GLOBAL
374 This is how you add a global init callback. Global callbacks happen for
376 every context for any hub or stack.
377 Test::Stream::Context->ON_INIT(sub {
379 my $ctx = shift;
380 ...
381 });
382 PER HUB
384 This is how you add an init callback for all contexts created for a
386 given hub. These callbacks will not run for other hubs.
387 $hub->add_context_init(sub {
389 my $ctx = shift;
390 ...
391 });
392 PER CONTEXT
394 This is how you specify an init hook that will only run if your call to
396 context() generates a new context. The callback will be ignored if
397 context() is returning an existing context.
398 my $ctx = context(on_init => sub {
400 my $ctx = shift;
401 ...
402 });
403 RELEASE HOOKS
405 These are called whenever a context is released. That means when the
406 last reference to the instance is about to be destroyed. These hooks
407 are NOT called every time "$ctx->release" is called.
408 GLOBAL
410 This is how you add a global release callback. Global callbacks happen
412 for every context for any hub or stack.
413 Test::Stream::Context->ON_RELEASE(sub {
415 my $ctx = shift;
416 ...
417 });
418 PER HUB
420 This is how you add a release callback for all contexts created for a
422 given hub. These callbacks will not run for other hubs.
423 $hub->add_context_release(sub {
425 my $ctx = shift;
426 ...
427 });
428 PER CONTEXT
430 This is how you add release callbacks directly to a context. The
432 callback will ALWAYS be added to the context that gets returned, it
433 does not matter if a new one is generated, or if an existing one is
434 returned.
435 my $ctx = context(on_release => sub {
437 my $ctx = shift;
438 ...
439 });
440
442 The source code repository for Test::Stream can be found at
443 http://github.com/Test-More/Test-Stream/.
444
446 Chad Granum <exodist@cpan.org>
447
449 Chad Granum <exodist@cpan.org>
450 Kent Fredric <kentnl@cpan.org>
451
453 Copyright 2015 Chad Granum <exodist7@gmail.com>.
454 This program is free software; you can redistribute it and/or modify it
456 under the same terms as Perl itself.
457 See http://dev.perl.org/licenses/
459perl v5.36.0 2023-01-20 Test::Stream::Context(3)