Debian Codegraph @

upstream/debian-unstable/man3/Test2::API.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "Test2::API 3perl"
58 .TH Test2::API 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::API \- Primary interface for writing Test2 based testing tools.
65 .SH "***INTERNALS NOTE***"
66 .IX Header "***INTERNALS NOTE***"
67 \&\fBThe internals of this package are subject to change at any time!\fR The public
68 methods provided will not change in backwards-incompatible ways (once there is
69 a stable release), but the underlying implementation details might.
70 \&\fBDo not break encapsulation here!\fR
71 .PP
72 Currently the implementation is to create a single instance of the
73 Test2::API::Instance Object. All class methods defer to the single
74 instance. There is no public access to the singleton, and that is intentional.
75 The class methods provided by this package provide the only functionality
76 publicly exposed.
77 .PP
78 This is done primarily to avoid the problems Test::Builder had by exposing its
79 singleton. We do not want anyone to replace this singleton, rebless it, or
80 directly muck with its internals. If you need to do something and cannot
81 because of the restrictions placed here, then please report it as an issue. If
82 possible, we will create a way for you to implement your functionality without
83 exposing things that should not be exposed.
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 This package exports all the functions necessary to write and/or verify testing
87 tools. Using these building blocks you can begin writing test tools very
88 quickly. You are also provided with tools that help you to test the tools you
89 write.
90 .SH SYNOPSIS
91 .IX Header "SYNOPSIS"
92 .SS "WRITING A TOOL"
93 .IX Subsection "WRITING A TOOL"
94 The \f(CWcontext()\fR method is your primary interface into the Test2 framework.
95 .PP
96 .Vb 2
97 \& package My::Ok;
98 \& use Test2::API qw/context/;
99 \&
100 \& our @EXPORT = qw/my_ok/;
101 \& use base \*(AqExporter\*(Aq;
102 \&
103 \& # Just like ok() from Test::More
104 \& sub my_ok($;$) {
105 \& my ($bool, $name) = @_;
106 \& my $ctx = context(); # Get a context
107 \& $ctx\->ok($bool, $name);
108 \& $ctx\->release; # Release the context
109 \& return $bool;
110 \& }
111 .Ve
112 .PP
113 See Test2::API::Context for a list of methods available on the context object.
114 .SS "TESTING YOUR TOOLS"
115 .IX Subsection "TESTING YOUR TOOLS"
116 The \f(CW\*(C`intercept { ... }\*(C'\fR tool lets you temporarily intercept all events
117 generated by the test system:
118 .PP
119 .Vb 1
120 \& use Test2::API qw/intercept/;
121 \&
122 \& use My::Ok qw/my_ok/;
123 \&
124 \& my $events = intercept {
125 \& # These events are not displayed
126 \& my_ok(1, "pass");
127 \& my_ok(0, "fail");
128 \& };
129 .Ve
130 .PP
131 As of version 1.302178 this now returns an arrayref that is also an instance of
132 Test2::API::InterceptResult. See the Test2::API::InterceptResult
133 documentation for details on how to best use it.
134 .SS "OTHER API FUNCTIONS"
135 .IX Subsection "OTHER API FUNCTIONS"
136 .Vb 10
137 \& use Test2::API qw{
138 \& test2_init_done
139 \& test2_stack
140 \& test2_set_is_end
141 \& test2_get_is_end
142 \& test2_ipc
143 \& test2_formatter_set
144 \& test2_formatter
145 \& test2_is_testing_done
146 \& };
147 \&
148 \& my $init = test2_init_done();
149 \& my $stack = test2_stack();
150 \& my $ipc = test2_ipc();
151 \&
152 \& test2_formatter_set($FORMATTER)
153 \& my $formatter = test2_formatter();
154 \&
155 \& ... And others ...
156 .Ve
157 .SH "MAIN API EXPORTS"
158 .IX Header "MAIN API EXPORTS"
159 All exports are optional. You must specify subs to import.
160 .PP
161 .Vb 1
162 \& use Test2::API qw/context intercept run_subtest/;
163 .Ve
164 .PP
165 This is the list of exports that are most commonly needed. If you are simply
166 writing a tool, then this is probably all you need. If you need something and
167 you cannot find it here, then you can also look at "OTHER API EXPORTS".
168 .PP
169 These exports lack the 'test2_' prefix because of how important/common they
170 are. Exports in the "OTHER API EXPORTS" section have the 'test2_' prefix to
171 ensure they stand out.
172 .SS context(...)
173 .IX Subsection "context(...)"
174 Usage:
175 .ie n .IP "$ctx = \fBcontext()\fR" 4
176 .el .IP "\f(CW$ctx\fR = \fBcontext()\fR" 4
177 .IX Item "$ctx = context()"
178 .PD 0
179 .ie n .IP "$ctx = context(%params)" 4
180 .el .IP "\f(CW$ctx\fR = context(%params)" 4
181 .IX Item "$ctx = context(%params)"
182 .PD
183 .PP
184 The \f(CWcontext()\fR function will always return the current context. If
185 there is already a context active, it will be returned. If there is not an
186 active context, one will be generated. When a context is generated it will
187 default to using the file and line number where the currently running sub was
188 called from.
189 .PP
190 Please see "CRITICAL DETAILS" in Test2::API::Context for important rules about
191 what you can and cannot do with a context once it is obtained.
192 .PP
193 \&\fBNote\fR This function will throw an exception if you ignore the context object
194 it returns.
195 .PP
196 \&\fBNote\fR On perls 5.14+ a depth check is used to ensure there are no context
197 leaks. This cannot be safely done on older perls due to
198 <https://rt.perl.org/Public/Bug/Display.html?id=127774>
199 You can forcefully enable it either by setting \f(CW\*(C`$ENV{T2_CHECK_DEPTH} = 1\*(C'\fR or
200 \&\f(CW\*(C`$Test2::API::DO_DEPTH_CHECK = 1\*(C'\fR \fBBEFORE\fR loading Test2::API.
201 .PP
202 \fIOPTIONAL PARAMETERS\fR
203 .IX Subsection "OPTIONAL PARAMETERS"
204 .PP
205 All parameters to \f(CW\*(C`context\*(C'\fR are optional.
206 .ie n .IP "level => $int" 4
207 .el .IP "level => \f(CW$int\fR" 4
208 .IX Item "level => $int"
209 If you must obtain a context in a sub deeper than your entry point you can use
210 this to tell it how many EXTRA stack frames to look back. If this option is not
211 provided the default of \f(CW0\fR is used.
212 .Sp
213 .Vb 6
214 \& sub third_party_tool {
215 \& my $sub = shift;
216 \& ... # Does not obtain a context
217 \& $sub\->();
218 \& ...
219 \& }
220 \&
221 \& third_party_tool(sub {
222 \& my $ctx = context(level => 1);
223 \& ...
224 \& $ctx\->release;
225 \& });
226 .Ve
227 .ie n .IP "wrapped => $int" 4
228 .el .IP "wrapped => \f(CW$int\fR" 4
229 .IX Item "wrapped => $int"
230 Use this if you need to write your own tool that wraps a call to \f(CWcontext()\fR
231 with the intent that it should return a context object.
232 .Sp
233 .Vb 7
234 \& sub my_context {
235 \& my %params = ( wrapped => 0, @_ );
236 \& $params{wrapped}++;
237 \& my $ctx = context(%params);
238 \& ...
239 \& return $ctx;
240 \& }
241 \&
242 \& sub my_tool {
243 \& my $ctx = my_context();
244 \& ...
245 \& $ctx\->release;
246 \& }
247 .Ve
248 .Sp
249 If you do not do this, then tools you call that also check for a context will
250 notice that the context they grabbed was created at the same stack depth, which
251 will trigger protective measures that warn you and destroy the existing
252 context.
253 .ie n .IP "stack => $stack" 4
254 .el .IP "stack => \f(CW$stack\fR" 4
255 .IX Item "stack => $stack"
256 Normally \f(CWcontext()\fR looks at the global hub stack. If you are maintaining
257 your own Test2::API::Stack instance you may pass it in to be used
258 instead of the global one.
259 .ie n .IP "hub => $hub" 4
260 .el .IP "hub => \f(CW$hub\fR" 4
261 .IX Item "hub => $hub"
262 Use this parameter if you want to obtain the context for a specific hub instead
263 of whatever one happens to be at the top of the stack.
264 .IP "on_init => sub { ... }" 4
265 .IX Item "on_init => sub { ... }"
266 This lets you provide a callback sub that will be called \fBONLY\fR if your call
267 to \f(CWcontext()\fR generated a new context. The callback \fBWILL NOT\fR be called if
268 \&\f(CWcontext()\fR is returning an existing context. The only argument passed into
269 the callback will be the context object itself.
270 .Sp
271 .Vb 2
272 \& sub foo {
273 \& my $ctx = context(on_init => sub { \*(Aqwill run\*(Aq });
274 \&
275 \& my $inner = sub {
276 \& # This callback is not run since we are getting the existing
277 \& # context from our parent sub.
278 \& my $ctx = context(on_init => sub { \*(Aqwill NOT run\*(Aq });
279 \& $ctx\->release;
280 \& }
281 \& $inner\->();
282 \&
283 \& $ctx\->release;
284 \& }
285 .Ve
286 .IP "on_release => sub { ... }" 4
287 .IX Item "on_release => sub { ... }"
288 This lets you provide a callback sub that will be called when the context
289 instance is released. This callback will be added to the returned context even
290 if an existing context is returned. If multiple calls to context add callbacks,
291 then all will be called in reverse order when the context is finally released.
292 .Sp
293 .Vb 2
294 \& sub foo {
295 \& my $ctx = context(on_release => sub { \*(Aqwill run second\*(Aq });
296 \&
297 \& my $inner = sub {
298 \& my $ctx = context(on_release => sub { \*(Aqwill run first\*(Aq });
299 \&
300 \& # Neither callback runs on this release
301 \& $ctx\->release;
302 \& }
303 \& $inner\->();
304 \&
305 \& # Both callbacks run here.
306 \& $ctx\->release;
307 \& }
308 .Ve
309 .SS release($;$)
310 .IX Subsection "release($;$)"
311 Usage:
312 .ie n .IP "release $ctx;" 4
313 .el .IP "release \f(CW$ctx\fR;" 4
314 .IX Item "release $ctx;"
315 .PD 0
316 .ie n .IP "release $ctx, ...;" 4
317 .el .IP "release \f(CW$ctx\fR, ...;" 4
318 .IX Item "release $ctx, ...;"
319 .PD
320 .PP
321 This is intended as a shortcut that lets you release your context and return a
322 value in one statement. This function will get your context, and an optional
323 return value. It will release your context, then return your value. Scalar
324 context is always assumed.
325 .PP
326 .Vb 3
327 \& sub tool {
328 \& my $ctx = context();
329 \& ...
330 \&
331 \& return release $ctx, 1;
332 \& }
333 .Ve
334 .PP
335 This tool is most useful when you want to return the value you get from calling
336 a function that needs to see the current context:
337 .PP
338 .Vb 4
339 \& my $ctx = context();
340 \& my $out = some_tool(...);
341 \& $ctx\->release;
342 \& return $out;
343 .Ve
344 .PP
345 We can combine the last 3 lines of the above like so:
346 .PP
347 .Vb 2
348 \& my $ctx = context();
349 \& release $ctx, some_tool(...);
350 .Ve
351 .SS context_do(&;@)
352 .IX Subsection "context_do(&;@)"
353 Usage:
354 .PP
355 .Vb 3
356 \& sub my_tool {
357 \& context_do {
358 \& my $ctx = shift;
359 \&
360 \& my (@args) = @_;
361 \&
362 \& $ctx\->ok(1, "pass");
363 \&
364 \& ...
365 \&
366 \& # No need to call $ctx\->release, done for you on scope exit.
367 \& } @_;
368 \& }
369 .Ve
370 .PP
371 Using this inside your test tool takes care of a lot of boilerplate for you. It
372 will ensure a context is acquired. It will capture and rethrow any exception. It
373 will ensure the context is released when you are done. It preserves the
374 subroutine call context (list, scalar, void).
375 .PP
376 This is the safest way to write a test tool. The only two downsides to this are a
377 slight performance decrease, and some extra indentation in your source. If the
378 indentation is a problem for you then you can take a peek at the next section.
379 .SS no_context(&;$)
380 .IX Subsection "no_context(&;$)"
381 Usage:
382 .IP "no_context { ... };" 4
383 .IX Item "no_context { ... };"
384 .PD 0
385 .ie n .IP "no_context { ... } $hid;" 4
386 .el .IP "no_context { ... } \f(CW$hid\fR;" 4
387 .IX Item "no_context { ... } $hid;"
388 .PD
389 .Vb 4
390 \& sub my_tool(&) {
391 \& my $code = shift;
392 \& my $ctx = context();
393 \& ...
394 \&
395 \& no_context {
396 \& # Things in here will not see our current context, they get a new
397 \& # one.
398 \&
399 \& $code\->();
400 \& };
401 \&
402 \& ...
403 \& $ctx\->release;
404 \& };
405 .Ve
406 .PP
407 This tool will hide a context for the provided block of code. This means any
408 tools run inside the block will get a completely new context if they acquire
409 one. The new context will be inherited by tools nested below the one that
410 acquired it.
411 .PP
412 This will normally hide the current context for the top hub. If you need to
413 hide the context for a different hub you can pass in the optional \f(CW$hid\fR
414 parameter.
415 .SS intercept(&)
416 .IX Subsection "intercept(&)"
417 Usage:
418 .PP
419 .Vb 5
420 \& my $events = intercept {
421 \& ok(1, "pass");
422 \& ok(0, "fail");
423 \& ...
424 \& };
425 .Ve
426 .PP
427 This function takes a codeblock as its only argument, and it has a prototype.
428 It will execute the codeblock, intercepting any generated events in the
429 process. It will return an array reference with all the generated event
430 objects. All events should be subclasses of Test2::Event.
431 .PP
432 As of version 1.302178 the events array that is returned is blssed as an
433 Test2::API::InterceptResult instance. Test2::API::InterceptResult
434 Provides a helpful interface for filtering and/or inspecting the events list
435 overall, or individual events within the list.
436 .PP
437 This is intended to help you test your test code. This is not intended for
438 people simply writing tests.
439 .SS run_subtest(...)
440 .IX Subsection "run_subtest(...)"
441 Usage:
442 .PP
443 .Vb 1
444 \& run_subtest($NAME, \e&CODE, $BUFFERED, @ARGS)
445 \&
446 \& # or
447 \&
448 \& run_subtest($NAME, \e&CODE, \e%PARAMS, @ARGS)
449 .Ve
450 .PP
451 This will run the provided codeblock with the args in \f(CW@args\fR. This codeblock
452 will be run as a subtest. A subtest is an isolated test state that is condensed
453 into a single Test2::Event::Subtest event, which contains all events
454 generated inside the subtest.
455 .PP
456 \fIARGUMENTS:\fR
457 .IX Subsection "ARGUMENTS:"
458 .ie n .IP $NAME 4
459 .el .IP \f(CW$NAME\fR 4
460 .IX Item "$NAME"
461 The name of the subtest.
462 .IP \e&CODE 4
463 .IX Item "&CODE"
464 The code to run inside the subtest.
465 .ie n .IP "$BUFFERED or \e%PARAMS" 4
466 .el .IP "\f(CW$BUFFERED\fR or \e%PARAMS" 4
467 .IX Item "$BUFFERED or %PARAMS"
468 If this is a simple scalar then it will be treated as a boolean for the
469 \&'buffered' setting. If this is a hash reference then it will be used as a
470 parameters hash. The param hash will be used for hub construction (with the
471 specified keys removed).
472 .Sp
473 Keys that are removed and used by run_subtest:
474 .RS 4
475 .ie n .IP "'buffered' => $bool" 4
476 .el .IP "'buffered' => \f(CW$bool\fR" 4
477 .IX Item "'buffered' => $bool"
478 Toggle buffered status.
479 .ie n .IP "'inherit_trace' => $bool" 4
480 .el .IP "'inherit_trace' => \f(CW$bool\fR" 4
481 .IX Item "'inherit_trace' => $bool"
482 Normally the subtest hub is pushed and the sub is allowed to generate its own
483 root context for the hub. When this setting is turned on a root context will be
484 created for the hub that shares the same trace as the current context.
485 .Sp
486 Set this to true if your tool is producing subtests without user-specified
487 subs.
488 .ie n .IP "'no_fork' => $bool" 4
489 .el .IP "'no_fork' => \f(CW$bool\fR" 4
490 .IX Item "'no_fork' => $bool"
491 Defaults to off. Normally forking inside a subtest will actually fork the
492 subtest, resulting in 2 final subtest events. This parameter will turn off that
493 behavior, only the original process/thread will return a final subtest event.
494 .RE
495 .RS 4
496 .RE
497 .ie n .IP @ARGS 4
498 .el .IP \f(CW@ARGS\fR 4
499 .IX Item "@ARGS"
500 Any extra arguments you want passed into the subtest code.
501 .PP
502 \fIBUFFERED VS UNBUFFERED (OR STREAMED)\fR
503 .IX Subsection "BUFFERED VS UNBUFFERED (OR STREAMED)"
504 .PP
505 Normally all events inside and outside a subtest are sent to the formatter
506 immediately by the hub. Sometimes it is desirable to hold off sending events
507 within a subtest until the subtest is complete. This usually depends on the
508 formatter being used.
509 .IP "Things not affected by this flag" 4
510 .IX Item "Things not affected by this flag"
511 In both cases events are generated and stored in an array. This array is
512 eventually used to populate the \f(CW\*(C`subevents\*(C'\fR attribute on the
513 Test2::Event::Subtest event that is generated at the end of the subtest.
514 This flag has no effect on this part, it always happens.
515 .Sp
516 At the end of the subtest, the final Test2::Event::Subtest event is sent to
517 the formatter.
518 .IP "Things that are affected by this flag" 4
519 .IX Item "Things that are affected by this flag"
520 The \f(CW\*(C`buffered\*(C'\fR attribute of the Test2::Event::Subtest event will be set to
521 the value of this flag. This means any formatter, listener, etc which looks at
522 the event will know if it was buffered.
523 .IP "Things that are formatter dependent" 4
524 .IX Item "Things that are formatter dependent"
525 Events within a buffered subtest may or may not be sent to the formatter as
526 they happen. If a formatter fails to specify then the default is to \fBNOT SEND\fR
527 the events as they are generated, instead the formatter can pull them from the
528 \&\f(CW\*(C`subevents\*(C'\fR attribute.
529 .Sp
530 A formatter can specify by implementing the \f(CWhide_buffered()\fR method. If this
531 method returns true then events generated inside a buffered subtest will not be
532 sent independently of the final subtest event.
533 .PP
534 An example of how this is used is the Test2::Formatter::TAP formatter. For
535 unbuffered subtests the events are rendered as they are generated. At the end
536 of the subtest, the final subtest event is rendered, but the \f(CW\*(C`subevents\*(C'\fR
537 attribute is ignored. For buffered subtests the opposite occurs, the events are
538 NOT rendered as they are generated, instead the \f(CW\*(C`subevents\*(C'\fR attribute is used
539 to render them all at once. This is useful when running subtests tests in
540 parallel, since without it the output from subtests would be interleaved
541 together.
542 .SH "OTHER API EXPORTS"
543 .IX Header "OTHER API EXPORTS"
544 Exports in this section are not commonly needed. These all have the 'test2_'
545 prefix to help ensure they stand out. You should look at the "MAIN API
546 EXPORTS" section before looking here. This section is one where "Great power
547 comes with great responsibility". It is possible to break things badly if you
548 are not careful with these.
549 .PP
550 All exports are optional. You need to list which ones you want at import time:
551 .PP
552 .Vb 1
553 \& use Test2::API qw/test2_init_done .../;
554 .Ve
555 .SS "STATUS AND INITIALIZATION STATE"
556 .IX Subsection "STATUS AND INITIALIZATION STATE"
557 These provide access to internal state and object instances.
558 .ie n .IP "$bool = \fBtest2_init_done()\fR" 4
559 .el .IP "\f(CW$bool\fR = \fBtest2_init_done()\fR" 4
560 .IX Item "$bool = test2_init_done()"
561 This will return true if the stack and IPC instances have already been
562 initialized. It will return false if they have not. Init happens as late as
563 possible. It happens as soon as a tool requests the IPC instance, the
564 formatter, or the stack.
565 .ie n .IP "$bool = \fBtest2_load_done()\fR" 4
566 .el .IP "\f(CW$bool\fR = \fBtest2_load_done()\fR" 4
567 .IX Item "$bool = test2_load_done()"
568 This will simply return the boolean value of the loaded flag. If Test2 has
569 finished loading this will be true, otherwise false. Loading is considered
570 complete the first time a tool requests a context.
571 .IP \fBtest2_set_is_end()\fR 4
572 .IX Item "test2_set_is_end()"
573 .PD 0
574 .IP test2_set_is_end($bool) 4
575 .IX Item "test2_set_is_end($bool)"
576 .PD
577 This is used to toggle Test2's belief that the END phase has already started.
578 With no arguments this will set it to true. With arguments it will set it to
579 the first argument's value.
580 .Sp
581 This is used to prevent the use of \f(CWcaller()\fR in END blocks which can cause
582 segfaults. This is only necessary in some persistent environments that may have
583 multiple END phases.
584 .ie n .IP "$bool = \fBtest2_get_is_end()\fR" 4
585 .el .IP "\f(CW$bool\fR = \fBtest2_get_is_end()\fR" 4
586 .IX Item "$bool = test2_get_is_end()"
587 Check if Test2 believes it is the END phase.
588 .ie n .IP "$stack = \fBtest2_stack()\fR" 4
589 .el .IP "\f(CW$stack\fR = \fBtest2_stack()\fR" 4
590 .IX Item "$stack = test2_stack()"
591 This will return the global Test2::API::Stack instance. If this has not
592 yet been initialized it will be initialized now.
593 .ie n .IP "$bool = \fBtest2_is_testing_done()\fR" 4
594 .el .IP "\f(CW$bool\fR = \fBtest2_is_testing_done()\fR" 4
595 .IX Item "$bool = test2_is_testing_done()"
596 This will return true if testing is complete and no other events should be
597 sent. This is useful in things like warning handlers where you might want to
598 turn warnings into events, but need them to start acting like normal warnings
599 when testing is done.
600 .Sp
601 .Vb 2
602 \& $SIG{_\|_WARN_\|_} = sub {
603 \& my ($warning) = @_;
604 \&
605 \& if (test2_is_testing_done()) {
606 \& warn @_;
607 \& }
608 \& else {
609 \& my $ctx = context();
610 \& ...
611 \& $ctx\->release
612 \& }
613 \& }
614 .Ve
615 .IP test2_ipc_disable 4
616 .IX Item "test2_ipc_disable"
617 Disable IPC.
618 .ie n .IP "$bool = test2_ipc_disabled" 4
619 .el .IP "\f(CW$bool\fR = test2_ipc_disabled" 4
620 .IX Item "$bool = test2_ipc_disabled"
621 Check if IPC is disabled.
622 .IP \fBtest2_ipc_wait_enable()\fR 4
623 .IX Item "test2_ipc_wait_enable()"
624 .PD 0
625 .IP \fBtest2_ipc_wait_disable()\fR 4
626 .IX Item "test2_ipc_wait_disable()"
627 .ie n .IP "$bool = \fBtest2_ipc_wait_enabled()\fR" 4
628 .el .IP "\f(CW$bool\fR = \fBtest2_ipc_wait_enabled()\fR" 4
629 .IX Item "$bool = test2_ipc_wait_enabled()"
630 .PD
631 These can be used to turn IPC waiting on and off, or check the current value of
632 the flag.
633 .Sp
634 Waiting is turned on by default. Waiting will cause the parent process/thread
635 to wait until all child processes and threads are finished before exiting. You
636 will almost never want to turn this off.
637 .ie n .IP "$bool = \fBtest2_no_wait()\fR" 4
638 .el .IP "\f(CW$bool\fR = \fBtest2_no_wait()\fR" 4
639 .IX Item "$bool = test2_no_wait()"
640 .PD 0
641 .IP test2_no_wait($bool) 4
642 .IX Item "test2_no_wait($bool)"
643 .PD
644 \&\fBDISCOURAGED\fR: This is a confusing interface, it is better to use
645 \&\f(CWtest2_ipc_wait_enable()\fR, \f(CWtest2_ipc_wait_disable()\fR and
646 \&\f(CWtest2_ipc_wait_enabled()\fR.
647 .Sp
648 This can be used to get/set the no_wait status. Waiting is turned on by
649 default. Waiting will cause the parent process/thread to wait until all child
650 processes and threads are finished before exiting. You will almost never want
651 to turn this off.
652 .ie n .IP "$fh = \fBtest2_stdout()\fR" 4
653 .el .IP "\f(CW$fh\fR = \fBtest2_stdout()\fR" 4
654 .IX Item "$fh = test2_stdout()"
655 .PD 0
656 .ie n .IP "$fh = \fBtest2_stderr()\fR" 4
657 .el .IP "\f(CW$fh\fR = \fBtest2_stderr()\fR" 4
658 .IX Item "$fh = test2_stderr()"
659 .PD
660 These functions return the filehandles that test output should be written to.
661 They are primarily useful when writing a custom formatter and code that turns
662 events into actual output (TAP, etc.). They will return a dupe of the original
663 filehandles that formatted output can be sent to regardless of whatever state
664 the currently running test may have left STDOUT and STDERR in.
665 .IP \fBtest2_reset_io()\fR 4
666 .IX Item "test2_reset_io()"
667 Re-dupe the internal filehandles returned by \f(CWtest2_stdout()\fR and
668 \&\f(CWtest2_stderr()\fR from the current STDOUT and STDERR. You shouldn't need to do
669 this except in very peculiar situations (for example, you're testing a new
670 formatter and you need control over where the formatter is sending its output.)
671 .SS "BEHAVIOR HOOKS"
672 .IX Subsection "BEHAVIOR HOOKS"
673 These are hooks that allow you to add custom behavior to actions taken by Test2
674 and tools built on top of it.
675 .IP "test2_add_callback_exit(sub { ... })" 4
676 .IX Item "test2_add_callback_exit(sub { ... })"
677 This can be used to add a callback that is called after all testing is done. This
678 is too late to add additional results, the main use of this callback is to set the
679 exit code.
680 .Sp
681 .Vb 6
682 \& test2_add_callback_exit(
683 \& sub {
684 \& my ($context, $exit, \e$new_exit) = @_;
685 \& ...
686 \& }
687 \& );
688 .Ve
689 .Sp
690 The \f(CW$context\fR passed in will be an instance of Test2::API::Context. The
691 \&\f(CW$exit\fR argument will be the original exit code before anything modified it.
692 \&\f(CW$$new_exit\fR is a reference to the new exit code. You may modify this to
693 change the exit code. Please note that \f(CW$$new_exit\fR may already be different
694 from \f(CW$exit\fR
695 .IP "test2_add_callback_post_load(sub { ... })" 4
696 .IX Item "test2_add_callback_post_load(sub { ... })"
697 Add a callback that will be called when Test2 is finished loading. This
698 means the callback will be run once, the first time a context is obtained.
699 If Test2 has already finished loading then the callback will be run immediately.
700 .IP "test2_add_callback_testing_done(sub { ... })" 4
701 .IX Item "test2_add_callback_testing_done(sub { ... })"
702 This adds your coderef as a follow-up to the root hub after Test2 is finished loading.
703 .Sp
704 This is essentially a helper to do the following:
705 .Sp
706 .Vb 4
707 \& test2_add_callback_post_load(sub {
708 \& my $stack = test2_stack();
709 \& $stack\->top; # Ensure we have a hub
710 \& my ($hub) = Test2::API::test2_stack\->all;
711 \&
712 \& $hub\->set_active(1);
713 \&
714 \& $hub\->follow_up(sub { ... }); # <\-\- Your coderef here
715 \& });
716 .Ve
717 .IP "test2_add_callback_context_acquire(sub { ... })" 4
718 .IX Item "test2_add_callback_context_acquire(sub { ... })"
719 Add a callback that will be called every time someone tries to acquire a
720 context. This will be called on EVERY call to \f(CWcontext()\fR. It gets a single
721 argument, a reference to the hash of parameters being used the construct the
722 context. This is your chance to change the parameters by directly altering the
723 hash.
724 .Sp
725 .Vb 4
726 \& test2_add_callback_context_acquire(sub {
727 \& my $params = shift;
728 \& $params\->{level}++;
729 \& });
730 .Ve
731 .Sp
732 This is a very scary API function. Please do not use this unless you need to.
733 This is here for Test::Builder and backwards compatibility. This has you
734 directly manipulate the hash instead of returning a new one for performance
735 reasons.
736 .IP "test2_add_callback_context_init(sub { ... })" 4
737 .IX Item "test2_add_callback_context_init(sub { ... })"
738 Add a callback that will be called every time a new context is created. The
739 callback will receive the newly created context as its only argument.
740 .IP "test2_add_callback_context_release(sub { ... })" 4
741 .IX Item "test2_add_callback_context_release(sub { ... })"
742 Add a callback that will be called every time a context is released. The
743 callback will receive the released context as its only argument.
744 .IP "test2_add_callback_pre_subtest(sub { ... })" 4
745 .IX Item "test2_add_callback_pre_subtest(sub { ... })"
746 Add a callback that will be called every time a subtest is going to be
747 run. The callback will receive the subtest name, coderef, and any
748 arguments.
749 .ie n .IP "@list = \fBtest2_list_context_acquire_callbacks()\fR" 4
750 .el .IP "\f(CW@list\fR = \fBtest2_list_context_acquire_callbacks()\fR" 4
751 .IX Item "@list = test2_list_context_acquire_callbacks()"
752 Return all the context acquire callback references.
753 .ie n .IP "@list = \fBtest2_list_context_init_callbacks()\fR" 4
754 .el .IP "\f(CW@list\fR = \fBtest2_list_context_init_callbacks()\fR" 4
755 .IX Item "@list = test2_list_context_init_callbacks()"
756 Returns all the context init callback references.
757 .ie n .IP "@list = \fBtest2_list_context_release_callbacks()\fR" 4
758 .el .IP "\f(CW@list\fR = \fBtest2_list_context_release_callbacks()\fR" 4
759 .IX Item "@list = test2_list_context_release_callbacks()"
760 Returns all the context release callback references.
761 .ie n .IP "@list = \fBtest2_list_exit_callbacks()\fR" 4
762 .el .IP "\f(CW@list\fR = \fBtest2_list_exit_callbacks()\fR" 4
763 .IX Item "@list = test2_list_exit_callbacks()"
764 Returns all the exit callback references.
765 .ie n .IP "@list = \fBtest2_list_post_load_callbacks()\fR" 4
766 .el .IP "\f(CW@list\fR = \fBtest2_list_post_load_callbacks()\fR" 4
767 .IX Item "@list = test2_list_post_load_callbacks()"
768 Returns all the post load callback references.
769 .ie n .IP "@list = \fBtest2_list_pre_subtest_callbacks()\fR" 4
770 .el .IP "\f(CW@list\fR = \fBtest2_list_pre_subtest_callbacks()\fR" 4
771 .IX Item "@list = test2_list_pre_subtest_callbacks()"
772 Returns all the pre-subtest callback references.
773 .IP "test2_add_uuid_via(sub { ... })" 4
774 .IX Item "test2_add_uuid_via(sub { ... })"
775 .PD 0
776 .ie n .IP "$sub = \fBtest2_add_uuid_via()\fR" 4
777 .el .IP "\f(CW$sub\fR = \fBtest2_add_uuid_via()\fR" 4
778 .IX Item "$sub = test2_add_uuid_via()"
779 .PD
780 This allows you to provide a UUID generator. If provided UUIDs will be attached
781 to all events, hubs, and contexts. This is useful for storing, tracking, and
782 linking these objects.
783 .Sp
784 The sub you provide should always return a unique identifier. Most things will
785 expect a proper UUID string, however nothing in Test2::API enforces this.
786 .Sp
787 The sub will receive exactly 1 argument, the type of thing being tagged
788 \&'context', 'hub', or 'event'. In the future additional things may be tagged, in
789 which case new strings will be passed in. These are purely informative, you can
790 (and usually should) ignore them.
791 .SS "IPC AND CONCURRENCY"
792 .IX Subsection "IPC AND CONCURRENCY"
793 These let you access, or specify, the IPC system internals.
794 .ie n .IP "$bool = \fBtest2_has_ipc()\fR" 4
795 .el .IP "\f(CW$bool\fR = \fBtest2_has_ipc()\fR" 4
796 .IX Item "$bool = test2_has_ipc()"
797 Check if IPC is enabled.
798 .ie n .IP "$ipc = \fBtest2_ipc()\fR" 4
799 .el .IP "\f(CW$ipc\fR = \fBtest2_ipc()\fR" 4
800 .IX Item "$ipc = test2_ipc()"
801 This will return the global Test2::IPC::Driver instance. If this has not yet
802 been initialized it will be initialized now.
803 .IP test2_ipc_add_driver($DRIVER) 4
804 .IX Item "test2_ipc_add_driver($DRIVER)"
805 Add an IPC driver to the list. This will add the driver to the start of the
806 list.
807 .ie n .IP "@drivers = \fBtest2_ipc_drivers()\fR" 4
808 .el .IP "\f(CW@drivers\fR = \fBtest2_ipc_drivers()\fR" 4
809 .IX Item "@drivers = test2_ipc_drivers()"
810 Get the list of IPC drivers.
811 .ie n .IP "$bool = \fBtest2_ipc_polling()\fR" 4
812 .el .IP "\f(CW$bool\fR = \fBtest2_ipc_polling()\fR" 4
813 .IX Item "$bool = test2_ipc_polling()"
814 Check if polling is enabled.
815 .IP \fBtest2_ipc_enable_polling()\fR 4
816 .IX Item "test2_ipc_enable_polling()"
817 Turn on polling. This will cull events from other processes and threads every
818 time a context is created.
819 .IP \fBtest2_ipc_disable_polling()\fR 4
820 .IX Item "test2_ipc_disable_polling()"
821 Turn off IPC polling.
822 .IP \fBtest2_ipc_enable_shm()\fR 4
823 .IX Item "test2_ipc_enable_shm()"
824 Legacy, this is currently a no-op that returns 0;
825 .IP test2_ipc_set_pending($uniq_val) 4
826 .IX Item "test2_ipc_set_pending($uniq_val)"
827 Tell other processes and events that an event is pending. \f(CW$uniq_val\fR should
828 be a unique value no other thread/process will generate.
829 .Sp
830 \&\fBNote:\fR After calling this \f(CWtest2_ipc_get_pending()\fR will return 1. This is
831 intentional, and not avoidable.
832 .ie n .IP "$pending = \fBtest2_ipc_get_pending()\fR" 4
833 .el .IP "\f(CW$pending\fR = \fBtest2_ipc_get_pending()\fR" 4
834 .IX Item "$pending = test2_ipc_get_pending()"
835 This returns \-1 if there is no way to check (assume yes)
836 .Sp
837 This returns 0 if there are (most likely) no pending events.
838 .Sp
839 This returns 1 if there are (likely) pending events. Upon return it will reset,
840 nothing else will be able to see that there were pending events.
841 .ie n .IP "$timeout = \fBtest2_ipc_get_timeout()\fR" 4
842 .el .IP "\f(CW$timeout\fR = \fBtest2_ipc_get_timeout()\fR" 4
843 .IX Item "$timeout = test2_ipc_get_timeout()"
844 .PD 0
845 .IP test2_ipc_set_timeout($timeout) 4
846 .IX Item "test2_ipc_set_timeout($timeout)"
847 .PD
848 Get/Set the timeout value for the IPC system. This timeout is how long the IPC
849 system will wait for child processes and threads to finish before aborting.
850 .Sp
851 The default value is \f(CW30\fR seconds.
852 .SS "MANAGING FORMATTERS"
853 .IX Subsection "MANAGING FORMATTERS"
854 These let you access, or specify, the formatters that can/should be used.
855 .ie n .IP "$formatter = test2_formatter" 4
856 .el .IP "\f(CW$formatter\fR = test2_formatter" 4
857 .IX Item "$formatter = test2_formatter"
858 This will return the global formatter class. This is not an instance. By
859 default the formatter is set to Test2::Formatter::TAP.
860 .Sp
861 You can override this default using the \f(CW\*(C`T2_FORMATTER\*(C'\fR environment variable.
862 .Sp
863 Normally 'Test2::Formatter::' is prefixed to the value in the
864 environment variable:
865 .Sp
866 .Vb 2
867 \& $ T2_FORMATTER=\*(AqTAP\*(Aq perl test.t # Use the Test2::Formatter::TAP formatter
868 \& $ T2_FORMATTER=\*(AqFoo\*(Aq perl test.t # Use the Test2::Formatter::Foo formatter
869 .Ve
870 .Sp
871 If you want to specify a full module name you use the '+' prefix:
872 .Sp
873 .Vb 1
874 \& $ T2_FORMATTER=\*(Aq+Foo::Bar\*(Aq perl test.t # Use the Foo::Bar formatter
875 .Ve
876 .IP test2_formatter_set($class_or_instance) 4
877 .IX Item "test2_formatter_set($class_or_instance)"
878 Set the global formatter class. This can only be set once. \fBNote:\fR This will
879 override anything specified in the 'T2_FORMATTER' environment variable.
880 .ie n .IP "@formatters = \fBtest2_formatters()\fR" 4
881 .el .IP "\f(CW@formatters\fR = \fBtest2_formatters()\fR" 4
882 .IX Item "@formatters = test2_formatters()"
883 Get a list of all loaded formatters.
884 .IP test2_formatter_add($class_or_instance) 4
885 .IX Item "test2_formatter_add($class_or_instance)"
886 Add a formatter to the list. Last formatter added is used at initialization. If
887 this is called after initialization a warning will be issued.
888 .SS "TIME STAMPS"
889 .IX Subsection "TIME STAMPS"
890 You can enable or disable timestamps in trace facets. They are disabled by
891 default for compatibility and performance reasons.
892 .IP \fBtest2_enable_trace_stamps()\fR 4
893 .IX Item "test2_enable_trace_stamps()"
894 Enable stamps in traces.
895 .IP \fBtest2_disable_trace_stamps()\fR 4
896 .IX Item "test2_disable_trace_stamps()"
897 Disable stamps in traces.
898 .ie n .IP "$bool = \fBtest2_trace_stamps_enabled()\fR" 4
899 .el .IP "\f(CW$bool\fR = \fBtest2_trace_stamps_enabled()\fR" 4
900 .IX Item "$bool = test2_trace_stamps_enabled()"
901 Check status of trace stamps.
902 .SH "OTHER EXAMPLES"
903 .IX Header "OTHER EXAMPLES"
904 See the \f(CW\*(C`/Examples/\*(C'\fR directory included in this distribution.
905 .SH "SEE ALSO"
906 .IX Header "SEE ALSO"
907 Test2::API::Context \- Detailed documentation of the context object.
908 .PP
909 Test2::IPC \- The IPC system used for threading/fork support.
910 .PP
911 Test2::Formatter \- Formatters such as TAP live here.
912 .PP
913 Test2::Event \- Events live in this namespace.
914 .PP
915 Test2::Hub \- All events eventually funnel through a hub. Custom hubs are how
916 \&\f(CWintercept()\fR and \f(CWrun_subtest()\fR are implemented.
917 .SH MAGIC
918 .IX Header "MAGIC"
919 This package has an END block. This END block is responsible for setting the
920 exit code based on the test results. This end block also calls the callbacks that
921 can be added to this package.
922 .SH SOURCE
923 .IX Header "SOURCE"
924 The source code repository for Test2 can be found at
925 <https://github.com/Test\-More/test\-more/>.
926 .SH MAINTAINERS
927 .IX Header "MAINTAINERS"
928 .IP "Chad Granum <[email protected]>" 4
929 .IX Item "Chad Granum <[email protected]>"
930 .SH AUTHORS
931 .IX Header "AUTHORS"
932 .PD 0
933 .IP "Chad Granum <[email protected]>" 4
934 .IX Item "Chad Granum <[email protected]>"
935 .PD
936 .SH COPYRIGHT
937 .IX Header "COPYRIGHT"
938 Copyright 2020 Chad Granum <[email protected]>.
939 .PP
940 This program is free software; you can redistribute it and/or
941 modify it under the same terms as Perl itself.
942 .PP
943 See <https://dev.perl.org/licenses/>