1package Test2::API; 2use strict; 3use warnings; 4 5use Time::HiRes qw/time/; 6use Test2::Util qw/USE_THREADS/; 7 8BEGIN { 9 $ENV{TEST_ACTIVE} ||= 1; 10 $ENV{TEST2_ACTIVE} = 1; 11} 12 13our $VERSION = '1.302194'; 14 15 16my $INST; 17my $ENDING = 0; 18sub test2_unset_is_end { $ENDING = 0 } 19sub test2_get_is_end { $ENDING } 20 21sub test2_set_is_end { 22 my $before = $ENDING; 23 ($ENDING) = @_ ? @_ : (1); 24 25 # Only send the event in a transition from false to true 26 return if $before; 27 return unless $ENDING; 28 29 return unless $INST; 30 my $stack = $INST->stack or return; 31 my $root = $stack->root or return; 32 33 return unless $root->count; 34 35 return unless $$ == $INST->pid; 36 return unless get_tid() == $INST->tid; 37 38 my $trace = Test2::EventFacet::Trace->new( 39 frame => [__PACKAGE__, __FILE__, __LINE__, __PACKAGE__ . '::test2_set_is_end'], 40 ); 41 my $ctx = Test2::API::Context->new( 42 trace => $trace, 43 hub => $root, 44 ); 45 46 $ctx->send_ev2(control => { phase => 'END', details => 'Transition to END phase' }); 47 48 1; 49} 50 51use Test2::API::Instance(\$INST); 52 53# Set the exit status 54END { 55 test2_set_is_end(); # See gh #16 56 $INST->set_exit(); 57} 58 59sub CLONE { 60 my $init = test2_init_done(); 61 my $load = test2_load_done(); 62 63 return if $init && $load; 64 65 require Carp; 66 Carp::croak "Test2 must be fully loaded before you start a new thread!\n"; 67} 68 69# See gh #16 70{ 71 no warnings; 72 INIT { eval 'END { test2_set_is_end() }; 1' or die $@ } 73} 74 75BEGIN { 76 no warnings 'once'; 77 if($] ge '5.014' || $ENV{T2_CHECK_DEPTH} || $Test2::API::DO_DEPTH_CHECK) { 78 *DO_DEPTH_CHECK = sub() { 1 }; 79 } 80 else { 81 *DO_DEPTH_CHECK = sub() { 0 }; 82 } 83} 84 85use Test2::EventFacet::Trace(); 86use Test2::Util::Trace(); # Legacy 87 88use Test2::Hub::Subtest(); 89use Test2::Hub::Interceptor(); 90use Test2::Hub::Interceptor::Terminator(); 91 92use Test2::Event::Ok(); 93use Test2::Event::Diag(); 94use Test2::Event::Note(); 95use Test2::Event::Plan(); 96use Test2::Event::Bail(); 97use Test2::Event::Exception(); 98use Test2::Event::Waiting(); 99use Test2::Event::Skip(); 100use Test2::Event::Subtest(); 101 102use Carp qw/carp croak confess/; 103use Scalar::Util qw/blessed weaken/; 104use Test2::Util qw/get_tid clone_io pkg_to_file gen_uid/; 105 106our @EXPORT_OK = qw{ 107 context release 108 context_do 109 no_context 110 intercept intercept_deep 111 run_subtest 112 113 test2_init_done 114 test2_load_done 115 test2_load 116 test2_start_preload 117 test2_stop_preload 118 test2_in_preload 119 test2_is_testing_done 120 121 test2_set_is_end 122 test2_unset_is_end 123 test2_get_is_end 124 125 test2_pid 126 test2_tid 127 test2_stack 128 test2_no_wait 129 test2_ipc_wait_enable 130 test2_ipc_wait_disable 131 test2_ipc_wait_enabled 132 133 test2_add_uuid_via 134 135 test2_add_callback_testing_done 136 137 test2_add_callback_context_aquire 138 test2_add_callback_context_acquire 139 test2_add_callback_context_init 140 test2_add_callback_context_release 141 test2_add_callback_exit 142 test2_add_callback_post_load 143 test2_add_callback_pre_subtest 144 test2_list_context_aquire_callbacks 145 test2_list_context_acquire_callbacks 146 test2_list_context_init_callbacks 147 test2_list_context_release_callbacks 148 test2_list_exit_callbacks 149 test2_list_post_load_callbacks 150 test2_list_pre_subtest_callbacks 151 152 test2_ipc 153 test2_has_ipc 154 test2_ipc_disable 155 test2_ipc_disabled 156 test2_ipc_drivers 157 test2_ipc_add_driver 158 test2_ipc_polling 159 test2_ipc_disable_polling 160 test2_ipc_enable_polling 161 test2_ipc_get_pending 162 test2_ipc_set_pending 163 test2_ipc_get_timeout 164 test2_ipc_set_timeout 165 166 test2_formatter 167 test2_formatters 168 test2_formatter_add 169 test2_formatter_set 170 171 test2_stdout 172 test2_stderr 173 test2_reset_io 174}; 175BEGIN { require Exporter; our @ISA = qw(Exporter) } 176 177my $STACK = $INST->stack; 178my $CONTEXTS = $INST->contexts; 179my $INIT_CBS = $INST->context_init_callbacks; 180my $ACQUIRE_CBS = $INST->context_acquire_callbacks; 181 182my $STDOUT = clone_io(\*STDOUT); 183my $STDERR = clone_io(\*STDERR); 184sub test2_stdout { $STDOUT ||= clone_io(\*STDOUT) } 185sub test2_stderr { $STDERR ||= clone_io(\*STDERR) } 186 187sub test2_post_preload_reset { 188 test2_reset_io(); 189 $INST->post_preload_reset; 190} 191 192sub test2_reset_io { 193 $STDOUT = clone_io(\*STDOUT); 194 $STDERR = clone_io(\*STDERR); 195} 196 197sub test2_init_done { $INST->finalized } 198sub test2_load_done { $INST->loaded } 199 200sub test2_load { $INST->load } 201sub test2_start_preload { $ENV{T2_IN_PRELOAD} = 1; $INST->start_preload } 202sub test2_stop_preload { $ENV{T2_IN_PRELOAD} = 0; $INST->stop_preload } 203sub test2_in_preload { $INST->preload } 204 205sub test2_pid { $INST->pid } 206sub test2_tid { $INST->tid } 207sub test2_stack { $INST->stack } 208sub test2_ipc_wait_enable { $INST->set_no_wait(0) } 209sub test2_ipc_wait_disable { $INST->set_no_wait(1) } 210sub test2_ipc_wait_enabled { !$INST->no_wait } 211 212sub test2_is_testing_done { 213 # No instance? VERY DONE! 214 return 1 unless $INST; 215 216 # No stack? tests must be done, it is created pretty early 217 my $stack = $INST->stack or return 1; 218 219 # Nothing on the stack, no root hub yet, likely have not started testing 220 return 0 unless @$stack; 221 222 # Stack has a slot for the root hub (see above) but it is undefined, likely 223 # garbage collected, test is done 224 my $root_hub = $stack->[0] or return 1; 225 226 # If the root hub is ended than testing is done. 227 return 1 if $root_hub->ended; 228 229 # Looks like we are still testing! 230 return 0; 231} 232 233sub test2_no_wait { 234 $INST->set_no_wait(@_) if @_; 235 $INST->no_wait; 236} 237 238sub test2_add_callback_testing_done { 239 my $cb = shift; 240 241 test2_add_callback_post_load(sub { 242 my $stack = test2_stack(); 243 $stack->top; # Insure we have a hub 244 my ($hub) = Test2::API::test2_stack->all; 245 246 $hub->set_active(1); 247 248 $hub->follow_up($cb); 249 }); 250 251 return; 252} 253 254sub test2_add_callback_context_acquire { $INST->add_context_acquire_callback(@_) } 255sub test2_add_callback_context_aquire { $INST->add_context_acquire_callback(@_) } 256sub test2_add_callback_context_init { $INST->add_context_init_callback(@_) } 257sub test2_add_callback_context_release { $INST->add_context_release_callback(@_) } 258sub test2_add_callback_exit { $INST->add_exit_callback(@_) } 259sub test2_add_callback_post_load { $INST->add_post_load_callback(@_) } 260sub test2_add_callback_pre_subtest { $INST->add_pre_subtest_callback(@_) } 261sub test2_list_context_aquire_callbacks { @{$INST->context_acquire_callbacks} } 262sub test2_list_context_acquire_callbacks { @{$INST->context_acquire_callbacks} } 263sub test2_list_context_init_callbacks { @{$INST->context_init_callbacks} } 264sub test2_list_context_release_callbacks { @{$INST->context_release_callbacks} } 265sub test2_list_exit_callbacks { @{$INST->exit_callbacks} } 266sub test2_list_post_load_callbacks { @{$INST->post_load_callbacks} } 267sub test2_list_pre_subtest_callbacks { @{$INST->pre_subtest_callbacks} } 268 269sub test2_add_uuid_via { 270 $INST->set_add_uuid_via(@_) if @_; 271 $INST->add_uuid_via(); 272} 273 274sub test2_ipc { $INST->ipc } 275sub test2_has_ipc { $INST->has_ipc } 276sub test2_ipc_disable { $INST->ipc_disable } 277sub test2_ipc_disabled { $INST->ipc_disabled } 278sub test2_ipc_add_driver { $INST->add_ipc_driver(@_) } 279sub test2_ipc_drivers { @{$INST->ipc_drivers} } 280sub test2_ipc_polling { $INST->ipc_polling } 281sub test2_ipc_enable_polling { $INST->enable_ipc_polling } 282sub test2_ipc_disable_polling { $INST->disable_ipc_polling } 283sub test2_ipc_get_pending { $INST->get_ipc_pending } 284sub test2_ipc_set_pending { $INST->set_ipc_pending(@_) } 285sub test2_ipc_set_timeout { $INST->set_ipc_timeout(@_) } 286sub test2_ipc_get_timeout { $INST->ipc_timeout() } 287sub test2_ipc_enable_shm { 0 } 288 289sub test2_formatter { 290 if ($ENV{T2_FORMATTER} && $ENV{T2_FORMATTER} =~ m/^(\+)?(.*)$/) { 291 my $formatter = $1 ? $2 : "Test2::Formatter::$2"; 292 my $file = pkg_to_file($formatter); 293 require $file; 294 return $formatter; 295 } 296 297 return $INST->formatter; 298} 299 300sub test2_formatters { @{$INST->formatters} } 301sub test2_formatter_add { $INST->add_formatter(@_) } 302sub test2_formatter_set { 303 my ($formatter) = @_; 304 croak "No formatter specified" unless $formatter; 305 croak "Global Formatter already set" if $INST->formatter_set; 306 $INST->set_formatter($formatter); 307} 308 309# Private, for use in Test2::API::Context 310sub _contexts_ref { $INST->contexts } 311sub _context_acquire_callbacks_ref { $INST->context_acquire_callbacks } 312sub _context_init_callbacks_ref { $INST->context_init_callbacks } 313sub _context_release_callbacks_ref { $INST->context_release_callbacks } 314sub _add_uuid_via_ref { \($INST->{Test2::API::Instance::ADD_UUID_VIA()}) } 315 316# Private, for use in Test2::IPC 317sub _set_ipc { $INST->set_ipc(@_) } 318 319sub context_do(&;@) { 320 my $code = shift; 321 my @args = @_; 322 323 my $ctx = context(level => 1); 324 325 my $want = wantarray; 326 327 my @out; 328 my $ok = eval { 329 $want ? @out = $code->($ctx, @args) : 330 defined($want) ? $out[0] = $code->($ctx, @args) : 331 $code->($ctx, @args) ; 332 1; 333 }; 334 my $err = $@; 335 336 $ctx->release; 337 338 die $err unless $ok; 339 340 return @out if $want; 341 return $out[0] if defined $want; 342 return; 343} 344 345sub no_context(&;$) { 346 my ($code, $hid) = @_; 347 $hid ||= $STACK->top->hid; 348 349 my $ctx = $CONTEXTS->{$hid}; 350 delete $CONTEXTS->{$hid}; 351 my $ok = eval { $code->(); 1 }; 352 my $err = $@; 353 354 $CONTEXTS->{$hid} = $ctx; 355 weaken($CONTEXTS->{$hid}); 356 357 die $err unless $ok; 358 359 return; 360}; 361 362my $UUID_VIA = _add_uuid_via_ref(); 363sub context { 364 # We need to grab these before anything else to ensure they are not 365 # changed. 366 my ($errno, $eval_error, $child_error, $extended_error) = (0 + $!, $@, $?, $^E); 367 368 my %params = (level => 0, wrapped => 0, @_); 369 370 # If something is getting a context then the sync system needs to be 371 # considered loaded... 372 $INST->load unless $INST->{loaded}; 373 374 croak "context() called, but return value is ignored" 375 unless defined wantarray; 376 377 my $stack = $params{stack} || $STACK; 378 my $hub = $params{hub} || (@$stack ? $stack->[-1] : $stack->top); 379 380 # Catch an edge case where we try to get context after the root hub has 381 # been garbage collected resulting in a stack that has a single undef 382 # hub 383 if (!$hub && !exists($params{hub}) && @$stack) { 384 my $msg = Carp::longmess("Attempt to get Test2 context after testing has completed (did you attempt a testing event after done_testing?)"); 385 386 # The error message is usually masked by the global destruction, so we have to print to STDER 387 print STDERR $msg; 388 389 # Make sure this is a failure, we are probably already in END, so set $? to change the exit code 390 $? = 1; 391 392 # Now we actually die to interrupt the program flow and avoid undefined his warnings 393 die $msg; 394 } 395 396 my $hid = $hub->{hid}; 397 my $current = $CONTEXTS->{$hid}; 398 399 $_->(\%params) for @$ACQUIRE_CBS; 400 map $_->(\%params), @{$hub->{_context_acquire}} if $hub->{_context_acquire}; 401 402 # This is for https://github.com/Test-More/test-more/issues/16 403 # and https://rt.perl.org/Public/Bug/Display.html?id=127774 404 my $phase = ${^GLOBAL_PHASE} || 'NA'; 405 my $end_phase = $ENDING || $phase eq 'END' || $phase eq 'DESTRUCT'; 406 407 my $level = 1 + $params{level}; 408 my ($pkg, $file, $line, $sub, @other) = $end_phase ? caller(0) : caller($level); 409 unless ($pkg || $end_phase) { 410 confess "Could not find context at depth $level" unless $params{fudge}; 411 ($pkg, $file, $line, $sub, @other) = caller(--$level) while ($level >= 0 && !$pkg); 412 } 413 414 my $depth = $level; 415 $depth++ while DO_DEPTH_CHECK && !$end_phase && (!$current || $depth <= $current->{_depth} + $params{wrapped}) && caller($depth + 1); 416 $depth -= $params{wrapped}; 417 my $depth_ok = !DO_DEPTH_CHECK || $end_phase || !$current || $current->{_depth} < $depth; 418 419 if ($current && $params{on_release} && $depth_ok) { 420 $current->{_on_release} ||= []; 421 push @{$current->{_on_release}} => $params{on_release}; 422 } 423 424 # I know this is ugly.... 425 ($!, $@, $?, $^E) = ($errno, $eval_error, $child_error, $extended_error) and return bless( 426 { 427 %$current, 428 _is_canon => undef, 429 errno => $errno, 430 eval_error => $eval_error, 431 child_error => $child_error, 432 _is_spawn => [$pkg, $file, $line, $sub], 433 }, 434 'Test2::API::Context' 435 ) if $current && $depth_ok; 436 437 # Handle error condition of bad level 438 if ($current) { 439 unless (${$current->{_aborted}}) { 440 _canon_error($current, [$pkg, $file, $line, $sub, $depth]) 441 unless $current->{_is_canon}; 442 443 _depth_error($current, [$pkg, $file, $line, $sub, $depth]) 444 unless $depth_ok; 445 } 446 447 $current->release if $current->{_is_canon}; 448 449 delete $CONTEXTS->{$hid}; 450 } 451 452 # Directly bless the object here, calling new is a noticeable performance 453 # hit with how often this needs to be called. 454 my $trace = bless( 455 { 456 frame => [$pkg, $file, $line, $sub], 457 pid => $$, 458 tid => get_tid(), 459 cid => gen_uid(), 460 hid => $hid, 461 nested => $hub->{nested}, 462 buffered => $hub->{buffered}, 463 464 full_caller => [$pkg, $file, $line, $sub, @other], 465 466 $$UUID_VIA ? ( 467 huuid => $hub->{uuid}, 468 uuid => ${$UUID_VIA}->('context'), 469 ) : (), 470 }, 471 'Test2::EventFacet::Trace' 472 ); 473 474 # Directly bless the object here, calling new is a noticeable performance 475 # hit with how often this needs to be called. 476 my $aborted = 0; 477 $current = bless( 478 { 479 _aborted => \$aborted, 480 stack => $stack, 481 hub => $hub, 482 trace => $trace, 483 _is_canon => 1, 484 _depth => $depth, 485 errno => $errno, 486 eval_error => $eval_error, 487 child_error => $child_error, 488 $params{on_release} ? (_on_release => [$params{on_release}]) : (), 489 }, 490 'Test2::API::Context' 491 ); 492 493 $CONTEXTS->{$hid} = $current; 494 weaken($CONTEXTS->{$hid}); 495 496 $_->($current) for @$INIT_CBS; 497 map $_->($current), @{$hub->{_context_init}} if $hub->{_context_init}; 498 499 $params{on_init}->($current) if $params{on_init}; 500 501 ($!, $@, $?, $^E) = ($errno, $eval_error, $child_error, $extended_error); 502 503 return $current; 504} 505 506sub _depth_error { 507 _existing_error(@_, <<" EOT"); 508context() was called to retrieve an existing context, however the existing 509context was created in a stack frame at the same, or deeper level. This usually 510means that a tool failed to release the context when it was finished. 511 EOT 512} 513 514sub _canon_error { 515 _existing_error(@_, <<" EOT"); 516context() was called to retrieve an existing context, however the existing 517context has an invalid internal state (!_canon_count). This should not normally 518happen unless something is mucking about with internals... 519 EOT 520} 521 522sub _existing_error { 523 my ($ctx, $details, $msg) = @_; 524 my ($pkg, $file, $line, $sub, $depth) = @$details; 525 526 my $oldframe = $ctx->{trace}->frame; 527 my $olddepth = $ctx->{_depth}; 528 529 # Older versions of Carp do not export longmess() function, so it needs to be called with package name 530 my $mess = Carp::longmess(); 531 532 warn <<" EOT"; 533$msg 534Old context details: 535 File: $oldframe->[1] 536 Line: $oldframe->[2] 537 Tool: $oldframe->[3] 538 Depth: $olddepth 539 540New context details: 541 File: $file 542 Line: $line 543 Tool: $sub 544 Depth: $depth 545 546Trace: $mess 547 548Removing the old context and creating a new one... 549 EOT 550} 551 552sub release($;$) { 553 $_[0]->release; 554 return $_[1]; 555} 556 557sub intercept(&) { 558 my $code = shift; 559 my $ctx = context(); 560 561 my $events = _intercept($code, deep => 0); 562 563 $ctx->release; 564 565 return $events; 566} 567 568sub intercept_deep(&) { 569 my $code = shift; 570 my $ctx = context(); 571 572 my $events = _intercept($code, deep => 1); 573 574 $ctx->release; 575 576 return $events; 577} 578 579sub _intercept { 580 my $code = shift; 581 my %params = @_; 582 my $ctx = context(); 583 584 my $ipc; 585 if (my $global_ipc = test2_ipc()) { 586 my $driver = blessed($global_ipc); 587 $ipc = $driver->new; 588 } 589 590 my $hub = Test2::Hub::Interceptor->new( 591 ipc => $ipc, 592 no_ending => 1, 593 ); 594 595 my @events; 596 $hub->listen(sub { push @events => $_[1] }, inherit => $params{deep}); 597 598 $ctx->stack->top; # Make sure there is a top hub before we begin. 599 $ctx->stack->push($hub); 600 601 my $trace = $ctx->trace; 602 my $state = {}; 603 $hub->clean_inherited(trace => $trace, state => $state); 604 605 my ($ok, $err) = (1, undef); 606 T2_SUBTEST_WRAPPER: { 607 # Do not use 'try' cause it localizes __DIE__ 608 $ok = eval { $code->(hub => $hub, context => $ctx->snapshot); 1 }; 609 $err = $@; 610 611 # They might have done 'BEGIN { skip_all => "whatever" }' 612 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && $err->isa('Test2::Hub::Interceptor::Terminator'))) { 613 $ok = 1; 614 $err = undef; 615 } 616 } 617 618 $hub->cull; 619 $ctx->stack->pop($hub); 620 621 $hub->restore_inherited(trace => $trace, state => $state); 622 623 $ctx->release; 624 625 die $err unless $ok; 626 627 $hub->finalize($trace, 1) 628 if $ok 629 && !$hub->no_ending 630 && !$hub->ended; 631 632 require Test2::API::InterceptResult; 633 return Test2::API::InterceptResult->new_from_ref(\@events); 634} 635 636sub run_subtest { 637 my ($name, $code, $params, @args) = @_; 638 639 $_->($name,$code,@args) 640 for Test2::API::test2_list_pre_subtest_callbacks(); 641 642 $params = {buffered => $params} unless ref $params; 643 my $inherit_trace = delete $params->{inherit_trace}; 644 645 my $ctx = context(); 646 647 my $parent = $ctx->hub; 648 649 # If a parent is buffered then the child must be as well. 650 my $buffered = $params->{buffered} || $parent->{buffered}; 651 652 $ctx->note($name) unless $buffered; 653 654 my $stack = $ctx->stack || $STACK; 655 my $hub = $stack->new_hub( 656 class => 'Test2::Hub::Subtest', 657 %$params, 658 buffered => $buffered, 659 ); 660 661 my @events; 662 $hub->listen(sub { push @events => $_[1] }); 663 664 if ($buffered) { 665 if (my $format = $hub->format) { 666 my $hide = $format->can('hide_buffered') ? $format->hide_buffered : 1; 667 $hub->format(undef) if $hide; 668 } 669 } 670 671 if ($inherit_trace) { 672 my $orig = $code; 673 $code = sub { 674 my $base_trace = $ctx->trace; 675 my $trace = $base_trace->snapshot(nested => 1 + $base_trace->nested); 676 my $st_ctx = Test2::API::Context->new( 677 trace => $trace, 678 hub => $hub, 679 ); 680 $st_ctx->do_in_context($orig, @args); 681 }; 682 } 683 684 my $start_stamp = time; 685 686 my ($ok, $err, $finished); 687 T2_SUBTEST_WRAPPER: { 688 # Do not use 'try' cause it localizes __DIE__ 689 $ok = eval { $code->(@args); 1 }; 690 $err = $@; 691 692 # They might have done 'BEGIN { skip_all => "whatever" }' 693 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && blessed($err) eq 'Test::Builder::Exception')) { 694 $ok = undef; 695 $err = undef; 696 } 697 else { 698 $finished = 1; 699 } 700 } 701 702 my $stop_stamp = time; 703 704 if ($params->{no_fork}) { 705 if ($$ != $ctx->trace->pid) { 706 warn $ok ? "Forked inside subtest, but subtest never finished!\n" : $err; 707 exit 255; 708 } 709 710 if (get_tid() != $ctx->trace->tid) { 711 warn $ok ? "Started new thread inside subtest, but thread never finished!\n" : $err; 712 exit 255; 713 } 714 } 715 elsif (!$parent->is_local && !$parent->ipc) { 716 warn $ok ? "A new process or thread was started inside subtest, but IPC is not enabled!\n" : $err; 717 exit 255; 718 } 719 720 $stack->pop($hub); 721 722 my $trace = $ctx->trace; 723 724 my $bailed = $hub->bailed_out; 725 726 if (!$finished) { 727 if ($bailed && !$buffered) { 728 $ctx->bail($bailed->reason); 729 } 730 elsif ($bailed && $buffered) { 731 $ok = 1; 732 } 733 else { 734 my $code = $hub->exit_code; 735 $ok = !$code; 736 $err = "Subtest ended with exit code $code" if $code; 737 } 738 } 739 740 $hub->finalize($trace->snapshot(huuid => $hub->uuid, hid => $hub->hid, nested => $hub->nested, buffered => $buffered), 1) 741 if $ok 742 && !$hub->no_ending 743 && !$hub->ended; 744 745 my $pass = $ok && $hub->is_passing; 746 my $e = $ctx->build_event( 747 'Subtest', 748 pass => $pass, 749 name => $name, 750 subtest_id => $hub->id, 751 subtest_uuid => $hub->uuid, 752 buffered => $buffered, 753 subevents => \@events, 754 start_stamp => $start_stamp, 755 stop_stamp => $stop_stamp, 756 ); 757 758 my $plan_ok = $hub->check_plan; 759 760 $ctx->hub->send($e); 761 762 $ctx->failure_diag($e) unless $e->pass; 763 764 $ctx->diag("Caught exception in subtest: $err") unless $ok; 765 766 $ctx->diag("Bad subtest plan, expected " . $hub->plan . " but ran " . $hub->count) 767 if defined($plan_ok) && !$plan_ok; 768 769 $ctx->bail($bailed->reason) if $bailed && $buffered; 770 771 $ctx->release; 772 return $pass; 773} 774 775# There is a use-cycle between API and API/Context. Context needs to use some 776# API functions as the package is compiling. Test2::API::context() needs 777# Test2::API::Context to be loaded, but we cannot 'require' the module there as 778# it causes a very noticeable performance impact with how often context() is 779# called. 780require Test2::API::Context; 781 7821; 783 784__END__ 785 786=pod 787 788=encoding UTF-8 789 790=head1 NAME 791 792Test2::API - Primary interface for writing Test2 based testing tools. 793 794=head1 ***INTERNALS NOTE*** 795 796B<The internals of this package are subject to change at any time!> The public 797methods provided will not change in backwards-incompatible ways (once there is 798a stable release), but the underlying implementation details might. 799B<Do not break encapsulation here!> 800 801Currently the implementation is to create a single instance of the 802L<Test2::API::Instance> Object. All class methods defer to the single 803instance. There is no public access to the singleton, and that is intentional. 804The class methods provided by this package provide the only functionality 805publicly exposed. 806 807This is done primarily to avoid the problems Test::Builder had by exposing its 808singleton. We do not want anyone to replace this singleton, rebless it, or 809directly muck with its internals. If you need to do something and cannot 810because of the restrictions placed here, then please report it as an issue. If 811possible, we will create a way for you to implement your functionality without 812exposing things that should not be exposed. 813 814=head1 DESCRIPTION 815 816This package exports all the functions necessary to write and/or verify testing 817tools. Using these building blocks you can begin writing test tools very 818quickly. You are also provided with tools that help you to test the tools you 819write. 820 821=head1 SYNOPSIS 822 823=head2 WRITING A TOOL 824 825The C<context()> method is your primary interface into the Test2 framework. 826 827 package My::Ok; 828 use Test2::API qw/context/; 829 830 our @EXPORT = qw/my_ok/; 831 use base 'Exporter'; 832 833 # Just like ok() from Test::More 834 sub my_ok($;$) { 835 my ($bool, $name) = @_; 836 my $ctx = context(); # Get a context 837 $ctx->ok($bool, $name); 838 $ctx->release; # Release the context 839 return $bool; 840 } 841 842See L<Test2::API::Context> for a list of methods available on the context object. 843 844=head2 TESTING YOUR TOOLS 845 846The C<intercept { ... }> tool lets you temporarily intercept all events 847generated by the test system: 848 849 use Test2::API qw/intercept/; 850 851 use My::Ok qw/my_ok/; 852 853 my $events = intercept { 854 # These events are not displayed 855 my_ok(1, "pass"); 856 my_ok(0, "fail"); 857 }; 858 859As of version 1.302178 this now returns an arrayref that is also an instance of 860L<Test2::API::InterceptResult>. See the L<Test2::API::InterceptResult> 861documentation for details on how to best use it. 862 863=head2 OTHER API FUNCTIONS 864 865 use Test2::API qw{ 866 test2_init_done 867 test2_stack 868 test2_set_is_end 869 test2_get_is_end 870 test2_ipc 871 test2_formatter_set 872 test2_formatter 873 test2_is_testing_done 874 }; 875 876 my $init = test2_init_done(); 877 my $stack = test2_stack(); 878 my $ipc = test2_ipc(); 879 880 test2_formatter_set($FORMATTER) 881 my $formatter = test2_formatter(); 882 883 ... And others ... 884 885=head1 MAIN API EXPORTS 886 887All exports are optional. You must specify subs to import. 888 889 use Test2::API qw/context intercept run_subtest/; 890 891This is the list of exports that are most commonly needed. If you are simply 892writing a tool, then this is probably all you need. If you need something and 893you cannot find it here, then you can also look at L</OTHER API EXPORTS>. 894 895These exports lack the 'test2_' prefix because of how important/common they 896are. Exports in the L</OTHER API EXPORTS> section have the 'test2_' prefix to 897ensure they stand out. 898 899=head2 context(...) 900 901Usage: 902 903=over 4 904 905=item $ctx = context() 906 907=item $ctx = context(%params) 908 909=back 910 911The C<context()> function will always return the current context. If 912there is already a context active, it will be returned. If there is not an 913active context, one will be generated. When a context is generated it will 914default to using the file and line number where the currently running sub was 915called from. 916 917Please see L<Test2::API::Context/"CRITICAL DETAILS"> for important rules about 918what you can and cannot do with a context once it is obtained. 919 920B<Note> This function will throw an exception if you ignore the context object 921it returns. 922 923B<Note> On perls 5.14+ a depth check is used to insure there are no context 924leaks. This cannot be safely done on older perls due to 925L<https://rt.perl.org/Public/Bug/Display.html?id=127774> 926You can forcefully enable it either by setting C<$ENV{T2_CHECK_DEPTH} = 1> or 927C<$Test2::API::DO_DEPTH_CHECK = 1> B<BEFORE> loading L<Test2::API>. 928 929=head3 OPTIONAL PARAMETERS 930 931All parameters to C<context> are optional. 932 933=over 4 934 935=item level => $int 936 937If you must obtain a context in a sub deeper than your entry point you can use 938this to tell it how many EXTRA stack frames to look back. If this option is not 939provided the default of C<0> is used. 940 941 sub third_party_tool { 942 my $sub = shift; 943 ... # Does not obtain a context 944 $sub->(); 945 ... 946 } 947 948 third_party_tool(sub { 949 my $ctx = context(level => 1); 950 ... 951 $ctx->release; 952 }); 953 954=item wrapped => $int 955 956Use this if you need to write your own tool that wraps a call to C<context()> 957with the intent that it should return a context object. 958 959 sub my_context { 960 my %params = ( wrapped => 0, @_ ); 961 $params{wrapped}++; 962 my $ctx = context(%params); 963 ... 964 return $ctx; 965 } 966 967 sub my_tool { 968 my $ctx = my_context(); 969 ... 970 $ctx->release; 971 } 972 973If you do not do this, then tools you call that also check for a context will 974notice that the context they grabbed was created at the same stack depth, which 975will trigger protective measures that warn you and destroy the existing 976context. 977 978=item stack => $stack 979 980Normally C<context()> looks at the global hub stack. If you are maintaining 981your own L<Test2::API::Stack> instance you may pass it in to be used 982instead of the global one. 983 984=item hub => $hub 985 986Use this parameter if you want to obtain the context for a specific hub instead 987of whatever one happens to be at the top of the stack. 988 989=item on_init => sub { ... } 990 991This lets you provide a callback sub that will be called B<ONLY> if your call 992to C<context()> generated a new context. The callback B<WILL NOT> be called if 993C<context()> is returning an existing context. The only argument passed into 994the callback will be the context object itself. 995 996 sub foo { 997 my $ctx = context(on_init => sub { 'will run' }); 998 999 my $inner = sub { 1000 # This callback is not run since we are getting the existing 1001 # context from our parent sub. 1002 my $ctx = context(on_init => sub { 'will NOT run' }); 1003 $ctx->release; 1004 } 1005 $inner->(); 1006 1007 $ctx->release; 1008 } 1009 1010=item on_release => sub { ... } 1011 1012This lets you provide a callback sub that will be called when the context 1013instance is released. This callback will be added to the returned context even 1014if an existing context is returned. If multiple calls to context add callbacks, 1015then all will be called in reverse order when the context is finally released. 1016 1017 sub foo { 1018 my $ctx = context(on_release => sub { 'will run second' }); 1019 1020 my $inner = sub { 1021 my $ctx = context(on_release => sub { 'will run first' }); 1022 1023 # Neither callback runs on this release 1024 $ctx->release; 1025 } 1026 $inner->(); 1027 1028 # Both callbacks run here. 1029 $ctx->release; 1030 } 1031 1032=back 1033 1034=head2 release($;$) 1035 1036Usage: 1037 1038=over 4 1039 1040=item release $ctx; 1041 1042=item release $ctx, ...; 1043 1044=back 1045 1046This is intended as a shortcut that lets you release your context and return a 1047value in one statement. This function will get your context, and an optional 1048return value. It will release your context, then return your value. Scalar 1049context is always assumed. 1050 1051 sub tool { 1052 my $ctx = context(); 1053 ... 1054 1055 return release $ctx, 1; 1056 } 1057 1058This tool is most useful when you want to return the value you get from calling 1059a function that needs to see the current context: 1060 1061 my $ctx = context(); 1062 my $out = some_tool(...); 1063 $ctx->release; 1064 return $out; 1065 1066We can combine the last 3 lines of the above like so: 1067 1068 my $ctx = context(); 1069 release $ctx, some_tool(...); 1070 1071=head2 context_do(&;@) 1072 1073Usage: 1074 1075 sub my_tool { 1076 context_do { 1077 my $ctx = shift; 1078 1079 my (@args) = @_; 1080 1081 $ctx->ok(1, "pass"); 1082 1083 ... 1084 1085 # No need to call $ctx->release, done for you on scope exit. 1086 } @_; 1087 } 1088 1089Using this inside your test tool takes care of a lot of boilerplate for you. It 1090will ensure a context is acquired. It will capture and rethrow any exception. It 1091will insure the context is released when you are done. It preserves the 1092subroutine call context (array, scalar, void). 1093 1094This is the safest way to write a test tool. The only two downsides to this are a 1095slight performance decrease, and some extra indentation in your source. If the 1096indentation is a problem for you then you can take a peek at the next section. 1097 1098=head2 no_context(&;$) 1099 1100Usage: 1101 1102=over 4 1103 1104=item no_context { ... }; 1105 1106=item no_context { ... } $hid; 1107 1108 sub my_tool(&) { 1109 my $code = shift; 1110 my $ctx = context(); 1111 ... 1112 1113 no_context { 1114 # Things in here will not see our current context, they get a new 1115 # one. 1116 1117 $code->(); 1118 }; 1119 1120 ... 1121 $ctx->release; 1122 }; 1123 1124=back 1125 1126This tool will hide a context for the provided block of code. This means any 1127tools run inside the block will get a completely new context if they acquire 1128one. The new context will be inherited by tools nested below the one that 1129acquired it. 1130 1131This will normally hide the current context for the top hub. If you need to 1132hide the context for a different hub you can pass in the optional C<$hid> 1133parameter. 1134 1135=head2 intercept(&) 1136 1137Usage: 1138 1139 my $events = intercept { 1140 ok(1, "pass"); 1141 ok(0, "fail"); 1142 ... 1143 }; 1144 1145This function takes a codeblock as its only argument, and it has a prototype. 1146It will execute the codeblock, intercepting any generated events in the 1147process. It will return an array reference with all the generated event 1148objects. All events should be subclasses of L<Test2::Event>. 1149 1150As of version 1.302178 the events array that is returned is blssed as an 1151L<Test2::API::InterceptResult> instance. L<Test2::API::InterceptResult> 1152Provides a helpful interface for filtering and/or inspecting the events list 1153overall, or individual events within the list. 1154 1155This is intended to help you test your test code. This is not intended for 1156people simply writing tests. 1157 1158=head2 run_subtest(...) 1159 1160Usage: 1161 1162 run_subtest($NAME, \&CODE, $BUFFERED, @ARGS) 1163 1164 # or 1165 1166 run_subtest($NAME, \&CODE, \%PARAMS, @ARGS) 1167 1168This will run the provided codeblock with the args in C<@args>. This codeblock 1169will be run as a subtest. A subtest is an isolated test state that is condensed 1170into a single L<Test2::Event::Subtest> event, which contains all events 1171generated inside the subtest. 1172 1173=head3 ARGUMENTS: 1174 1175=over 4 1176 1177=item $NAME 1178 1179The name of the subtest. 1180 1181=item \&CODE 1182 1183The code to run inside the subtest. 1184 1185=item $BUFFERED or \%PARAMS 1186 1187If this is a simple scalar then it will be treated as a boolean for the 1188'buffered' setting. If this is a hash reference then it will be used as a 1189parameters hash. The param hash will be used for hub construction (with the 1190specified keys removed). 1191 1192Keys that are removed and used by run_subtest: 1193 1194=over 4 1195 1196=item 'buffered' => $bool 1197 1198Toggle buffered status. 1199 1200=item 'inherit_trace' => $bool 1201 1202Normally the subtest hub is pushed and the sub is allowed to generate its own 1203root context for the hub. When this setting is turned on a root context will be 1204created for the hub that shares the same trace as the current context. 1205 1206Set this to true if your tool is producing subtests without user-specified 1207subs. 1208 1209=item 'no_fork' => $bool 1210 1211Defaults to off. Normally forking inside a subtest will actually fork the 1212subtest, resulting in 2 final subtest events. This parameter will turn off that 1213behavior, only the original process/thread will return a final subtest event. 1214 1215=back 1216 1217=item @ARGS 1218 1219Any extra arguments you want passed into the subtest code. 1220 1221=back 1222 1223=head3 BUFFERED VS UNBUFFERED (OR STREAMED) 1224 1225Normally all events inside and outside a subtest are sent to the formatter 1226immediately by the hub. Sometimes it is desirable to hold off sending events 1227within a subtest until the subtest is complete. This usually depends on the 1228formatter being used. 1229 1230=over 4 1231 1232=item Things not effected by this flag 1233 1234In both cases events are generated and stored in an array. This array is 1235eventually used to populate the C<subevents> attribute on the 1236L<Test2::Event::Subtest> event that is generated at the end of the subtest. 1237This flag has no effect on this part, it always happens. 1238 1239At the end of the subtest, the final L<Test2::Event::Subtest> event is sent to 1240the formatter. 1241 1242=item Things that are effected by this flag 1243 1244The C<buffered> attribute of the L<Test2::Event::Subtest> event will be set to 1245the value of this flag. This means any formatter, listener, etc which looks at 1246the event will know if it was buffered. 1247 1248=item Things that are formatter dependant 1249 1250Events within a buffered subtest may or may not be sent to the formatter as 1251they happen. If a formatter fails to specify then the default is to B<NOT SEND> 1252the events as they are generated, instead the formatter can pull them from the 1253C<subevents> attribute. 1254 1255A formatter can specify by implementing the C<hide_buffered()> method. If this 1256method returns true then events generated inside a buffered subtest will not be 1257sent independently of the final subtest event. 1258 1259=back 1260 1261An example of how this is used is the L<Test2::Formatter::TAP> formatter. For 1262unbuffered subtests the events are rendered as they are generated. At the end 1263of the subtest, the final subtest event is rendered, but the C<subevents> 1264attribute is ignored. For buffered subtests the opposite occurs, the events are 1265NOT rendered as they are generated, instead the C<subevents> attribute is used 1266to render them all at once. This is useful when running subtests tests in 1267parallel, since without it the output from subtests would be interleaved 1268together. 1269 1270=head1 OTHER API EXPORTS 1271 1272Exports in this section are not commonly needed. These all have the 'test2_' 1273prefix to help ensure they stand out. You should look at the L</MAIN API 1274EXPORTS> section before looking here. This section is one where "Great power 1275comes with great responsibility". It is possible to break things badly if you 1276are not careful with these. 1277 1278All exports are optional. You need to list which ones you want at import time: 1279 1280 use Test2::API qw/test2_init_done .../; 1281 1282=head2 STATUS AND INITIALIZATION STATE 1283 1284These provide access to internal state and object instances. 1285 1286=over 4 1287 1288=item $bool = test2_init_done() 1289 1290This will return true if the stack and IPC instances have already been 1291initialized. It will return false if they have not. Init happens as late as 1292possible. It happens as soon as a tool requests the IPC instance, the 1293formatter, or the stack. 1294 1295=item $bool = test2_load_done() 1296 1297This will simply return the boolean value of the loaded flag. If Test2 has 1298finished loading this will be true, otherwise false. Loading is considered 1299complete the first time a tool requests a context. 1300 1301=item test2_set_is_end() 1302 1303=item test2_set_is_end($bool) 1304 1305This is used to toggle Test2's belief that the END phase has already started. 1306With no arguments this will set it to true. With arguments it will set it to 1307the first argument's value. 1308 1309This is used to prevent the use of C<caller()> in END blocks which can cause 1310segfaults. This is only necessary in some persistent environments that may have 1311multiple END phases. 1312 1313=item $bool = test2_get_is_end() 1314 1315Check if Test2 believes it is the END phase. 1316 1317=item $stack = test2_stack() 1318 1319This will return the global L<Test2::API::Stack> instance. If this has not 1320yet been initialized it will be initialized now. 1321 1322=item $bool = test2_is_testing_done() 1323 1324This will return true if testing is complete and no other events should be 1325sent. This is useful in things like warning handlers where you might want to 1326turn warnings into events, but need them to start acting like normal warnings 1327when testing is done. 1328 1329 $SIG{__WARN__} = sub { 1330 my ($warning) = @_; 1331 1332 if (test2_is_testing_done()) { 1333 warn @_; 1334 } 1335 else { 1336 my $ctx = context(); 1337 ... 1338 $ctx->release 1339 } 1340 } 1341 1342=item test2_ipc_disable 1343 1344Disable IPC. 1345 1346=item $bool = test2_ipc_diabled 1347 1348Check if IPC is disabled. 1349 1350=item test2_ipc_wait_enable() 1351 1352=item test2_ipc_wait_disable() 1353 1354=item $bool = test2_ipc_wait_enabled() 1355 1356These can be used to turn IPC waiting on and off, or check the current value of 1357the flag. 1358 1359Waiting is turned on by default. Waiting will cause the parent process/thread 1360to wait until all child processes and threads are finished before exiting. You 1361will almost never want to turn this off. 1362 1363=item $bool = test2_no_wait() 1364 1365=item test2_no_wait($bool) 1366 1367B<DISCOURAGED>: This is a confusing interface, it is better to use 1368C<test2_ipc_wait_enable()>, C<test2_ipc_wait_disable()> and 1369C<test2_ipc_wait_enabled()>. 1370 1371This can be used to get/set the no_wait status. Waiting is turned on by 1372default. Waiting will cause the parent process/thread to wait until all child 1373processes and threads are finished before exiting. You will almost never want 1374to turn this off. 1375 1376=item $fh = test2_stdout() 1377 1378=item $fh = test2_stderr() 1379 1380These functions return the filehandles that test output should be written to. 1381They are primarily useful when writing a custom formatter and code that turns 1382events into actual output (TAP, etc.). They will return a dupe of the original 1383filehandles that formatted output can be sent to regardless of whatever state 1384the currently running test may have left STDOUT and STDERR in. 1385 1386=item test2_reset_io() 1387 1388Re-dupe the internal filehandles returned by C<test2_stdout()> and 1389C<test2_stderr()> from the current STDOUT and STDERR. You shouldn't need to do 1390this except in very peculiar situations (for example, you're testing a new 1391formatter and you need control over where the formatter is sending its output.) 1392 1393=back 1394 1395=head2 BEHAVIOR HOOKS 1396 1397These are hooks that allow you to add custom behavior to actions taken by Test2 1398and tools built on top of it. 1399 1400=over 4 1401 1402=item test2_add_callback_exit(sub { ... }) 1403 1404This can be used to add a callback that is called after all testing is done. This 1405is too late to add additional results, the main use of this callback is to set the 1406exit code. 1407 1408 test2_add_callback_exit( 1409 sub { 1410 my ($context, $exit, \$new_exit) = @_; 1411 ... 1412 } 1413 ); 1414 1415The C<$context> passed in will be an instance of L<Test2::API::Context>. The 1416C<$exit> argument will be the original exit code before anything modified it. 1417C<$$new_exit> is a reference to the new exit code. You may modify this to 1418change the exit code. Please note that C<$$new_exit> may already be different 1419from C<$exit> 1420 1421=item test2_add_callback_post_load(sub { ... }) 1422 1423Add a callback that will be called when Test2 is finished loading. This 1424means the callback will be run once, the first time a context is obtained. 1425If Test2 has already finished loading then the callback will be run immediately. 1426 1427=item test2_add_callback_testing_done(sub { ... }) 1428 1429This adds your coderef as a follow-up to the root hub after Test2 is finished loading. 1430 1431This is essentially a helper to do the following: 1432 1433 test2_add_callback_post_load(sub { 1434 my $stack = test2_stack(); 1435 $stack->top; # Insure we have a hub 1436 my ($hub) = Test2::API::test2_stack->all; 1437 1438 $hub->set_active(1); 1439 1440 $hub->follow_up(sub { ... }); # <-- Your coderef here 1441 }); 1442 1443=item test2_add_callback_context_acquire(sub { ... }) 1444 1445Add a callback that will be called every time someone tries to acquire a 1446context. This will be called on EVERY call to C<context()>. It gets a single 1447argument, a reference to the hash of parameters being used the construct the 1448context. This is your chance to change the parameters by directly altering the 1449hash. 1450 1451 test2_add_callback_context_acquire(sub { 1452 my $params = shift; 1453 $params->{level}++; 1454 }); 1455 1456This is a very scary API function. Please do not use this unless you need to. 1457This is here for L<Test::Builder> and backwards compatibility. This has you 1458directly manipulate the hash instead of returning a new one for performance 1459reasons. 1460 1461=item test2_add_callback_context_init(sub { ... }) 1462 1463Add a callback that will be called every time a new context is created. The 1464callback will receive the newly created context as its only argument. 1465 1466=item test2_add_callback_context_release(sub { ... }) 1467 1468Add a callback that will be called every time a context is released. The 1469callback will receive the released context as its only argument. 1470 1471=item test2_add_callback_pre_subtest(sub { ... }) 1472 1473Add a callback that will be called every time a subtest is going to be 1474run. The callback will receive the subtest name, coderef, and any 1475arguments. 1476 1477=item @list = test2_list_context_acquire_callbacks() 1478 1479Return all the context acquire callback references. 1480 1481=item @list = test2_list_context_init_callbacks() 1482 1483Returns all the context init callback references. 1484 1485=item @list = test2_list_context_release_callbacks() 1486 1487Returns all the context release callback references. 1488 1489=item @list = test2_list_exit_callbacks() 1490 1491Returns all the exit callback references. 1492 1493=item @list = test2_list_post_load_callbacks() 1494 1495Returns all the post load callback references. 1496 1497=item @list = test2_list_pre_subtest_callbacks() 1498 1499Returns all the pre-subtest callback references. 1500 1501=item test2_add_uuid_via(sub { ... }) 1502 1503=item $sub = test2_add_uuid_via() 1504 1505This allows you to provide a UUID generator. If provided UUIDs will be attached 1506to all events, hubs, and contexts. This is useful for storing, tracking, and 1507linking these objects. 1508 1509The sub you provide should always return a unique identifier. Most things will 1510expect a proper UUID string, however nothing in Test2::API enforces this. 1511 1512The sub will receive exactly 1 argument, the type of thing being tagged 1513'context', 'hub', or 'event'. In the future additional things may be tagged, in 1514which case new strings will be passed in. These are purely informative, you can 1515(and usually should) ignore them. 1516 1517=back 1518 1519=head2 IPC AND CONCURRENCY 1520 1521These let you access, or specify, the IPC system internals. 1522 1523=over 4 1524 1525=item $bool = test2_has_ipc() 1526 1527Check if IPC is enabled. 1528 1529=item $ipc = test2_ipc() 1530 1531This will return the global L<Test2::IPC::Driver> instance. If this has not yet 1532been initialized it will be initialized now. 1533 1534=item test2_ipc_add_driver($DRIVER) 1535 1536Add an IPC driver to the list. This will add the driver to the start of the 1537list. 1538 1539=item @drivers = test2_ipc_drivers() 1540 1541Get the list of IPC drivers. 1542 1543=item $bool = test2_ipc_polling() 1544 1545Check if polling is enabled. 1546 1547=item test2_ipc_enable_polling() 1548 1549Turn on polling. This will cull events from other processes and threads every 1550time a context is created. 1551 1552=item test2_ipc_disable_polling() 1553 1554Turn off IPC polling. 1555 1556=item test2_ipc_enable_shm() 1557 1558Legacy, this is currently a no-op that returns 0; 1559 1560=item test2_ipc_set_pending($uniq_val) 1561 1562Tell other processes and events that an event is pending. C<$uniq_val> should 1563be a unique value no other thread/process will generate. 1564 1565B<Note:> After calling this C<test2_ipc_get_pending()> will return 1. This is 1566intentional, and not avoidable. 1567 1568=item $pending = test2_ipc_get_pending() 1569 1570This returns -1 if there is no way to check (assume yes) 1571 1572This returns 0 if there are (most likely) no pending events. 1573 1574This returns 1 if there are (likely) pending events. Upon return it will reset, 1575nothing else will be able to see that there were pending events. 1576 1577=item $timeout = test2_ipc_get_timeout() 1578 1579=item test2_ipc_set_timeout($timeout) 1580 1581Get/Set the timeout value for the IPC system. This timeout is how long the IPC 1582system will wait for child processes and threads to finish before aborting. 1583 1584The default value is C<30> seconds. 1585 1586=back 1587 1588=head2 MANAGING FORMATTERS 1589 1590These let you access, or specify, the formatters that can/should be used. 1591 1592=over 4 1593 1594=item $formatter = test2_formatter 1595 1596This will return the global formatter class. This is not an instance. By 1597default the formatter is set to L<Test2::Formatter::TAP>. 1598 1599You can override this default using the C<T2_FORMATTER> environment variable. 1600 1601Normally 'Test2::Formatter::' is prefixed to the value in the 1602environment variable: 1603 1604 $ T2_FORMATTER='TAP' perl test.t # Use the Test2::Formatter::TAP formatter 1605 $ T2_FORMATTER='Foo' perl test.t # Use the Test2::Formatter::Foo formatter 1606 1607If you want to specify a full module name you use the '+' prefix: 1608 1609 $ T2_FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter 1610 1611=item test2_formatter_set($class_or_instance) 1612 1613Set the global formatter class. This can only be set once. B<Note:> This will 1614override anything specified in the 'T2_FORMATTER' environment variable. 1615 1616=item @formatters = test2_formatters() 1617 1618Get a list of all loaded formatters. 1619 1620=item test2_formatter_add($class_or_instance) 1621 1622Add a formatter to the list. Last formatter added is used at initialization. If 1623this is called after initialization a warning will be issued. 1624 1625=back 1626 1627=head1 OTHER EXAMPLES 1628 1629See the C</Examples/> directory included in this distribution. 1630 1631=head1 SEE ALSO 1632 1633L<Test2::API::Context> - Detailed documentation of the context object. 1634 1635L<Test2::IPC> - The IPC system used for threading/fork support. 1636 1637L<Test2::Formatter> - Formatters such as TAP live here. 1638 1639L<Test2::Event> - Events live in this namespace. 1640 1641L<Test2::Hub> - All events eventually funnel through a hub. Custom hubs are how 1642C<intercept()> and C<run_subtest()> are implemented. 1643 1644=head1 MAGIC 1645 1646This package has an END block. This END block is responsible for setting the 1647exit code based on the test results. This end block also calls the callbacks that 1648can be added to this package. 1649 1650=head1 SOURCE 1651 1652The source code repository for Test2 can be found at 1653F<http://github.com/Test-More/test-more/>. 1654 1655=head1 MAINTAINERS 1656 1657=over 4 1658 1659=item Chad Granum E<lt>exodist@cpan.orgE<gt> 1660 1661=back 1662 1663=head1 AUTHORS 1664 1665=over 4 1666 1667=item Chad Granum E<lt>exodist@cpan.orgE<gt> 1668 1669=back 1670 1671=head1 COPYRIGHT 1672 1673Copyright 2020 Chad Granum E<lt>exodist@cpan.orgE<gt>. 1674 1675This program is free software; you can redistribute it and/or 1676modify it under the same terms as Perl itself. 1677 1678See F<http://dev.perl.org/licenses/> 1679 1680=cut 1681