Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::API.3pm

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