5 use Test2::Util qw/USE_THREADS/;
8 $ENV{TEST_ACTIVE} ||= 1;
9 $ENV{TEST2_ACTIVE} = 1;
12 our $VERSION = '1.302171';
17 sub test2_unset_is_end { $ENDING = 0 }
18 sub test2_get_is_end { $ENDING }
20 sub test2_set_is_end {
22 ($ENDING) = @_ ? @_ : (1);
24 # Only send the event in a transition from false to true
26 return unless $ENDING;
29 my $stack = $INST->stack or return;
30 my $root = $stack->root or return;
32 return unless $root->count;
34 return unless $$ == $INST->pid;
35 return unless get_tid() == $INST->tid;
37 my $trace = Test2::EventFacet::Trace->new(
38 frame => [__PACKAGE__, __FILE__, __LINE__, __PACKAGE__ . '::test2_set_is_end'],
40 my $ctx = Test2::API::Context->new(
45 $ctx->send_ev2(control => { phase => 'END', details => 'Transition to END phase' });
50 use Test2::API::Instance(\$INST);
54 test2_set_is_end(); # See gh #16
59 my $init = test2_init_done();
60 my $load = test2_load_done();
62 return if $init && $load;
65 Carp::croak "Test2 must be fully loaded before you start a new thread!\n";
71 INIT { eval 'END { test2_set_is_end() }; 1' or die $@ }
76 if($] ge '5.014' || $ENV{T2_CHECK_DEPTH} || $Test2::API::DO_DEPTH_CHECK) {
77 *DO_DEPTH_CHECK = sub() { 1 };
80 *DO_DEPTH_CHECK = sub() { 0 };
84 use Test2::EventFacet::Trace();
85 use Test2::Util::Trace(); # Legacy
87 use Test2::Hub::Subtest();
88 use Test2::Hub::Interceptor();
89 use Test2::Hub::Interceptor::Terminator();
91 use Test2::Event::Ok();
92 use Test2::Event::Diag();
93 use Test2::Event::Note();
94 use Test2::Event::Plan();
95 use Test2::Event::Bail();
96 use Test2::Event::Exception();
97 use Test2::Event::Waiting();
98 use Test2::Event::Skip();
99 use Test2::Event::Subtest();
101 use Carp qw/carp croak confess/;
102 use Scalar::Util qw/blessed weaken/;
103 use Test2::Util qw/get_tid clone_io pkg_to_file gen_uid/;
109 intercept intercept_deep
118 test2_is_testing_done
128 test2_ipc_wait_enable
129 test2_ipc_wait_disable
130 test2_ipc_wait_enabled
134 test2_add_callback_testing_done
136 test2_add_callback_context_aquire
137 test2_add_callback_context_acquire
138 test2_add_callback_context_init
139 test2_add_callback_context_release
140 test2_add_callback_exit
141 test2_add_callback_post_load
142 test2_add_callback_pre_subtest
143 test2_list_context_aquire_callbacks
144 test2_list_context_acquire_callbacks
145 test2_list_context_init_callbacks
146 test2_list_context_release_callbacks
147 test2_list_exit_callbacks
148 test2_list_post_load_callbacks
149 test2_list_pre_subtest_callbacks
158 test2_ipc_disable_polling
159 test2_ipc_enable_polling
160 test2_ipc_get_pending
161 test2_ipc_set_pending
162 test2_ipc_get_timeout
163 test2_ipc_set_timeout
174 BEGIN { require Exporter; our @ISA = qw(Exporter) }
176 my $STACK = $INST->stack;
177 my $CONTEXTS = $INST->contexts;
178 my $INIT_CBS = $INST->context_init_callbacks;
179 my $ACQUIRE_CBS = $INST->context_acquire_callbacks;
181 my $STDOUT = clone_io(\*STDOUT);
182 my $STDERR = clone_io(\*STDERR);
183 sub test2_stdout { $STDOUT ||= clone_io(\*STDOUT) }
184 sub test2_stderr { $STDERR ||= clone_io(\*STDERR) }
186 sub test2_post_preload_reset {
188 $INST->post_preload_reset;
192 $STDOUT = clone_io(\*STDOUT);
193 $STDERR = clone_io(\*STDERR);
196 sub test2_init_done { $INST->finalized }
197 sub test2_load_done { $INST->loaded }
199 sub test2_load { $INST->load }
200 sub test2_start_preload { $ENV{T2_IN_PRELOAD} = 1; $INST->start_preload }
201 sub test2_stop_preload { $ENV{T2_IN_PRELOAD} = 0; $INST->stop_preload }
202 sub test2_in_preload { $INST->preload }
204 sub test2_pid { $INST->pid }
205 sub test2_tid { $INST->tid }
206 sub test2_stack { $INST->stack }
207 sub test2_ipc_wait_enable { $INST->set_no_wait(0) }
208 sub test2_ipc_wait_disable { $INST->set_no_wait(1) }
209 sub test2_ipc_wait_enabled { !$INST->no_wait }
211 sub test2_is_testing_done {
212 # No instance? VERY DONE!
213 return 1 unless $INST;
215 # No stack? tests must be done, it is created pretty early
216 my $stack = $INST->stack or return 1;
218 # Nothing on the stack, no root hub yet, likely have not started testing
219 return 0 unless @$stack;
221 # Stack has a slot for the root hub (see above) but it is undefined, likely
222 # garbage collected, test is done
223 my $root_hub = $stack->[0] or return 1;
225 # If the root hub is ended than testing is done.
226 return 1 if $root_hub->ended;
228 # Looks like we are still testing!
233 $INST->set_no_wait(@_) if @_;
237 sub test2_add_callback_testing_done {
240 test2_add_callback_post_load(sub {
241 my $stack = test2_stack();
242 $stack->top; # Insure we have a hub
243 my ($hub) = Test2::API::test2_stack->all;
247 $hub->follow_up($cb);
253 sub test2_add_callback_context_acquire { $INST->add_context_acquire_callback(@_) }
254 sub test2_add_callback_context_aquire { $INST->add_context_acquire_callback(@_) }
255 sub test2_add_callback_context_init { $INST->add_context_init_callback(@_) }
256 sub test2_add_callback_context_release { $INST->add_context_release_callback(@_) }
257 sub test2_add_callback_exit { $INST->add_exit_callback(@_) }
258 sub test2_add_callback_post_load { $INST->add_post_load_callback(@_) }
259 sub test2_add_callback_pre_subtest { $INST->add_pre_subtest_callback(@_) }
260 sub test2_list_context_aquire_callbacks { @{$INST->context_acquire_callbacks} }
261 sub test2_list_context_acquire_callbacks { @{$INST->context_acquire_callbacks} }
262 sub test2_list_context_init_callbacks { @{$INST->context_init_callbacks} }
263 sub test2_list_context_release_callbacks { @{$INST->context_release_callbacks} }
264 sub test2_list_exit_callbacks { @{$INST->exit_callbacks} }
265 sub test2_list_post_load_callbacks { @{$INST->post_load_callbacks} }
266 sub test2_list_pre_subtest_callbacks { @{$INST->pre_subtest_callbacks} }
268 sub test2_add_uuid_via {
269 $INST->set_add_uuid_via(@_) if @_;
270 $INST->add_uuid_via();
273 sub test2_ipc { $INST->ipc }
274 sub test2_has_ipc { $INST->has_ipc }
275 sub test2_ipc_disable { $INST->ipc_disable }
276 sub test2_ipc_disabled { $INST->ipc_disabled }
277 sub test2_ipc_add_driver { $INST->add_ipc_driver(@_) }
278 sub test2_ipc_drivers { @{$INST->ipc_drivers} }
279 sub test2_ipc_polling { $INST->ipc_polling }
280 sub test2_ipc_enable_polling { $INST->enable_ipc_polling }
281 sub test2_ipc_disable_polling { $INST->disable_ipc_polling }
282 sub test2_ipc_get_pending { $INST->get_ipc_pending }
283 sub test2_ipc_set_pending { $INST->set_ipc_pending(@_) }
284 sub test2_ipc_set_timeout { $INST->set_ipc_timeout(@_) }
285 sub test2_ipc_get_timeout { $INST->ipc_timeout() }
286 sub test2_ipc_enable_shm { 0 }
288 sub test2_formatter {
289 if ($ENV{T2_FORMATTER} && $ENV{T2_FORMATTER} =~ m/^(\+)?(.*)$/) {
290 my $formatter = $1 ? $2 : "Test2::Formatter::$2";
291 my $file = pkg_to_file($formatter);
296 return $INST->formatter;
299 sub test2_formatters { @{$INST->formatters} }
300 sub test2_formatter_add { $INST->add_formatter(@_) }
301 sub test2_formatter_set {
302 my ($formatter) = @_;
303 croak "No formatter specified" unless $formatter;
304 croak "Global Formatter already set" if $INST->formatter_set;
305 $INST->set_formatter($formatter);
308 # Private, for use in Test2::API::Context
309 sub _contexts_ref { $INST->contexts }
310 sub _context_acquire_callbacks_ref { $INST->context_acquire_callbacks }
311 sub _context_init_callbacks_ref { $INST->context_init_callbacks }
312 sub _context_release_callbacks_ref { $INST->context_release_callbacks }
313 sub _add_uuid_via_ref { \($INST->{Test2::API::Instance::ADD_UUID_VIA()}) }
315 # Private, for use in Test2::IPC
316 sub _set_ipc { $INST->set_ipc(@_) }
318 sub context_do(&;@) {
322 my $ctx = context(level => 1);
324 my $want = wantarray;
328 $want ? @out = $code->($ctx, @args) :
329 defined($want) ? $out[0] = $code->($ctx, @args) :
330 $code->($ctx, @args) ;
339 return @out if $want;
340 return $out[0] if defined $want;
344 sub no_context(&;$) {
345 my ($code, $hid) = @_;
346 $hid ||= $STACK->top->hid;
348 my $ctx = $CONTEXTS->{$hid};
349 delete $CONTEXTS->{$hid};
350 my $ok = eval { $code->(); 1 };
353 $CONTEXTS->{$hid} = $ctx;
354 weaken($CONTEXTS->{$hid});
361 my $UUID_VIA = _add_uuid_via_ref();
363 # We need to grab these before anything else to ensure they are not
365 my ($errno, $eval_error, $child_error, $extended_error) = (0 + $!, $@, $?, $^E);
367 my %params = (level => 0, wrapped => 0, @_);
369 # If something is getting a context then the sync system needs to be
370 # considered loaded...
371 $INST->load unless $INST->{loaded};
373 croak "context() called, but return value is ignored"
374 unless defined wantarray;
376 my $stack = $params{stack} || $STACK;
377 my $hub = $params{hub} || (@$stack ? $stack->[-1] : $stack->top);
379 # Catch an edge case where we try to get context after the root hub has
380 # been garbage collected resulting in a stack that has a single undef
382 if (!$hub && !exists($params{hub}) && @$stack) {
383 my $msg = Carp::longmess("Attempt to get Test2 context after testing has completed (did you attempt a testing event after done_testing?)");
385 # The error message is usually masked by the global destruction, so we have to print to STDER
388 # Make sure this is a failure, we are probably already in END, so set $? to change the exit code
391 # Now we actually die to interrupt the program flow and avoid undefined his warnings
395 my $hid = $hub->{hid};
396 my $current = $CONTEXTS->{$hid};
398 $_->(\%params) for @$ACQUIRE_CBS;
399 map $_->(\%params), @{$hub->{_context_acquire}} if $hub->{_context_acquire};
401 # This is for https://github.com/Test-More/test-more/issues/16
402 # and https://rt.perl.org/Public/Bug/Display.html?id=127774
403 my $phase = ${^GLOBAL_PHASE} || 'NA';
404 my $end_phase = $ENDING || $phase eq 'END' || $phase eq 'DESTRUCT';
406 my $level = 1 + $params{level};
407 my ($pkg, $file, $line, $sub) = $end_phase ? caller(0) : caller($level);
408 unless ($pkg || $end_phase) {
409 confess "Could not find context at depth $level" unless $params{fudge};
410 ($pkg, $file, $line, $sub) = caller(--$level) while ($level >= 0 && !$pkg);
414 $depth++ while DO_DEPTH_CHECK && !$end_phase && (!$current || $depth <= $current->{_depth} + $params{wrapped}) && caller($depth + 1);
415 $depth -= $params{wrapped};
416 my $depth_ok = !DO_DEPTH_CHECK || $end_phase || !$current || $current->{_depth} < $depth;
418 if ($current && $params{on_release} && $depth_ok) {
419 $current->{_on_release} ||= [];
420 push @{$current->{_on_release}} => $params{on_release};
423 # I know this is ugly....
424 ($!, $@, $?, $^E) = ($errno, $eval_error, $child_error, $extended_error) and return bless(
429 eval_error => $eval_error,
430 child_error => $child_error,
431 _is_spawn => [$pkg, $file, $line, $sub],
433 'Test2::API::Context'
434 ) if $current && $depth_ok;
436 # Handle error condition of bad level
438 unless (${$current->{_aborted}}) {
439 _canon_error($current, [$pkg, $file, $line, $sub, $depth])
440 unless $current->{_is_canon};
442 _depth_error($current, [$pkg, $file, $line, $sub, $depth])
446 $current->release if $current->{_is_canon};
448 delete $CONTEXTS->{$hid};
451 # Directly bless the object here, calling new is a noticeable performance
452 # hit with how often this needs to be called.
455 frame => [$pkg, $file, $line, $sub],
460 nested => $hub->{nested},
461 buffered => $hub->{buffered},
464 huuid => $hub->{uuid},
465 uuid => ${$UUID_VIA}->('context'),
468 'Test2::EventFacet::Trace'
471 # Directly bless the object here, calling new is a noticeable performance
472 # hit with how often this needs to be called.
476 _aborted => \$aborted,
483 eval_error => $eval_error,
484 child_error => $child_error,
485 $params{on_release} ? (_on_release => [$params{on_release}]) : (),
487 'Test2::API::Context'
490 $CONTEXTS->{$hid} = $current;
491 weaken($CONTEXTS->{$hid});
493 $_->($current) for @$INIT_CBS;
494 map $_->($current), @{$hub->{_context_init}} if $hub->{_context_init};
496 $params{on_init}->($current) if $params{on_init};
498 ($!, $@, $?, $^E) = ($errno, $eval_error, $child_error, $extended_error);
504 _existing_error(@_, <<" EOT");
505 context() was called to retrieve an existing context, however the existing
506 context was created in a stack frame at the same, or deeper level. This usually
507 means that a tool failed to release the context when it was finished.
512 _existing_error(@_, <<" EOT");
513 context() was called to retrieve an existing context, however the existing
514 context has an invalid internal state (!_canon_count). This should not normally
515 happen unless something is mucking about with internals...
519 sub _existing_error {
520 my ($ctx, $details, $msg) = @_;
521 my ($pkg, $file, $line, $sub, $depth) = @$details;
523 my $oldframe = $ctx->{trace}->frame;
524 my $olddepth = $ctx->{_depth};
526 # Older versions of Carp do not export longmess() function, so it needs to be called with package name
527 my $mess = Carp::longmess();
545 Removing the old context and creating a new one...
558 my $events = _intercept($code, deep => 0);
565 sub intercept_deep(&) {
569 my $events = _intercept($code, deep => 1);
582 if (my $global_ipc = test2_ipc()) {
583 my $driver = blessed($global_ipc);
587 my $hub = Test2::Hub::Interceptor->new(
593 $hub->listen(sub { push @events => $_[1] }, inherit => $params{deep});
595 $ctx->stack->top; # Make sure there is a top hub before we begin.
596 $ctx->stack->push($hub);
598 my ($ok, $err) = (1, undef);
599 T2_SUBTEST_WRAPPER: {
600 # Do not use 'try' cause it localizes __DIE__
601 $ok = eval { $code->(hub => $hub, context => $ctx->snapshot); 1 };
604 # They might have done 'BEGIN { skip_all => "whatever" }'
605 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && $err->isa('Test2::Hub::Interceptor::Terminator'))) {
612 $ctx->stack->pop($hub);
614 my $trace = $ctx->trace;
619 $hub->finalize($trace, 1)
628 my ($name, $code, $params, @args) = @_;
630 $_->($name,$code,@args)
631 for Test2::API::test2_list_pre_subtest_callbacks();
633 $params = {buffered => $params} unless ref $params;
634 my $inherit_trace = delete $params->{inherit_trace};
638 my $parent = $ctx->hub;
640 # If a parent is buffered then the child must be as well.
641 my $buffered = $params->{buffered} || $parent->{buffered};
643 $ctx->note($name) unless $buffered;
645 my $stack = $ctx->stack || $STACK;
646 my $hub = $stack->new_hub(
647 class => 'Test2::Hub::Subtest',
649 buffered => $buffered,
653 $hub->listen(sub { push @events => $_[1] });
656 if (my $format = $hub->format) {
657 my $hide = $format->can('hide_buffered') ? $format->hide_buffered : 1;
658 $hub->format(undef) if $hide;
662 if ($inherit_trace) {
665 my $base_trace = $ctx->trace;
666 my $trace = $base_trace->snapshot(nested => 1 + $base_trace->nested);
667 my $st_ctx = Test2::API::Context->new(
671 $st_ctx->do_in_context($orig, @args);
675 my ($ok, $err, $finished);
676 T2_SUBTEST_WRAPPER: {
677 # Do not use 'try' cause it localizes __DIE__
678 $ok = eval { $code->(@args); 1 };
681 # They might have done 'BEGIN { skip_all => "whatever" }'
682 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && blessed($err) eq 'Test::Builder::Exception')) {
691 if ($params->{no_fork}) {
692 if ($$ != $ctx->trace->pid) {
693 warn $ok ? "Forked inside subtest, but subtest never finished!\n" : $err;
697 if (get_tid() != $ctx->trace->tid) {
698 warn $ok ? "Started new thread inside subtest, but thread never finished!\n" : $err;
702 elsif (!$parent->is_local && !$parent->ipc) {
703 warn $ok ? "A new process or thread was started inside subtest, but IPC is not enabled!\n" : $err;
709 my $trace = $ctx->trace;
711 my $bailed = $hub->bailed_out;
714 if ($bailed && !$buffered) {
715 $ctx->bail($bailed->reason);
717 elsif ($bailed && $buffered) {
721 my $code = $hub->exit_code;
723 $err = "Subtest ended with exit code $code" if $code;
727 $hub->finalize($trace->snapshot(huuid => $hub->uuid, hid => $hub->hid, nested => $hub->nested, buffered => $buffered), 1)
732 my $pass = $ok && $hub->is_passing;
733 my $e = $ctx->build_event(
737 subtest_id => $hub->id,
738 subtest_uuid => $hub->uuid,
739 buffered => $buffered,
740 subevents => \@events,
743 my $plan_ok = $hub->check_plan;
747 $ctx->failure_diag($e) unless $e->pass;
749 $ctx->diag("Caught exception in subtest: $err") unless $ok;
751 $ctx->diag("Bad subtest plan, expected " . $hub->plan . " but ran " . $hub->count)
752 if defined($plan_ok) && !$plan_ok;
754 $ctx->bail($bailed->reason) if $bailed && $buffered;
760 # There is a use-cycle between API and API/Context. Context needs to use some
761 # API functions as the package is compiling. Test2::API::context() needs
762 # Test2::API::Context to be loaded, but we cannot 'require' the module there as
763 # it causes a very noticeable performance impact with how often context() is
765 require Test2::API::Context;
777 Test2::API - Primary interface for writing Test2 based testing tools.
779 =head1 ***INTERNALS NOTE***
781 B<The internals of this package are subject to change at any time!> The public
782 methods provided will not change in backwards-incompatible ways (once there is
783 a stable release), but the underlying implementation details might.
784 B<Do not break encapsulation here!>
786 Currently the implementation is to create a single instance of the
787 L<Test2::API::Instance> Object. All class methods defer to the single
788 instance. There is no public access to the singleton, and that is intentional.
789 The class methods provided by this package provide the only functionality
792 This is done primarily to avoid the problems Test::Builder had by exposing its
793 singleton. We do not want anyone to replace this singleton, rebless it, or
794 directly muck with its internals. If you need to do something and cannot
795 because of the restrictions placed here, then please report it as an issue. If
796 possible, we will create a way for you to implement your functionality without
797 exposing things that should not be exposed.
801 This package exports all the functions necessary to write and/or verify testing
802 tools. Using these building blocks you can begin writing test tools very
803 quickly. You are also provided with tools that help you to test the tools you
808 =head2 WRITING A TOOL
810 The C<context()> method is your primary interface into the Test2 framework.
813 use Test2::API qw/context/;
815 our @EXPORT = qw/my_ok/;
818 # Just like ok() from Test::More
820 my ($bool, $name) = @_;
821 my $ctx = context(); # Get a context
822 $ctx->ok($bool, $name);
823 $ctx->release; # Release the context
827 See L<Test2::API::Context> for a list of methods available on the context object.
829 =head2 TESTING YOUR TOOLS
831 The C<intercept { ... }> tool lets you temporarily intercept all events
832 generated by the test system:
834 use Test2::API qw/intercept/;
836 use My::Ok qw/my_ok/;
838 my $events = intercept {
839 # These events are not displayed
844 my_ok(@$events == 2, "got 2 events, the pass and the fail");
845 my_ok($events->[0]->pass, "first event passed");
846 my_ok(!$events->[1]->pass, "second event failed");
848 =head3 DEEP EVENT INTERCEPTION
850 Normally C<intercept { ... }> only intercepts events sent to the main hub (as
851 added by intercept itself). Nested hubs, such as those created by subtests,
852 will not be intercepted. This is normally what you will still see the nested
853 events by inspecting the subtest event. However there are times where you want
854 to verify each event as it is sent, in that case use C<intercept_deep { ... }>.
856 my $events = intercept_Deep {
857 buffered_subtest foo => sub {
862 C<$events> in this case will contain 3 items:
866 =item The event from C<ok(1, "pass")>
868 =item The plan event for the subtest
870 =item The subtest event itself, with the first 2 events nested inside it as children.
874 This lets you see the order in which the events were sent, unlike
875 C<intercept { ... }> which only lets you see events as the main hub sees them.
877 =head2 OTHER API FUNCTIONS
887 test2_is_testing_done
890 my $init = test2_init_done();
891 my $stack = test2_stack();
892 my $ipc = test2_ipc();
894 test2_formatter_set($FORMATTER)
895 my $formatter = test2_formatter();
899 =head1 MAIN API EXPORTS
901 All exports are optional. You must specify subs to import.
903 use Test2::API qw/context intercept run_subtest/;
905 This is the list of exports that are most commonly needed. If you are simply
906 writing a tool, then this is probably all you need. If you need something and
907 you cannot find it here, then you can also look at L</OTHER API EXPORTS>.
909 These exports lack the 'test2_' prefix because of how important/common they
910 are. Exports in the L</OTHER API EXPORTS> section have the 'test2_' prefix to
911 ensure they stand out.
919 =item $ctx = context()
921 =item $ctx = context(%params)
925 The C<context()> function will always return the current context. If
926 there is already a context active, it will be returned. If there is not an
927 active context, one will be generated. When a context is generated it will
928 default to using the file and line number where the currently running sub was
931 Please see L<Test2::API::Context/"CRITICAL DETAILS"> for important rules about
932 what you can and cannot do with a context once it is obtained.
934 B<Note> This function will throw an exception if you ignore the context object
937 B<Note> On perls 5.14+ a depth check is used to insure there are no context
938 leaks. This cannot be safely done on older perls due to
939 L<https://rt.perl.org/Public/Bug/Display.html?id=127774>
940 You can forcefully enable it either by setting C<$ENV{T2_CHECK_DEPTH} = 1> or
941 C<$Test2::API::DO_DEPTH_CHECK = 1> B<BEFORE> loading L<Test2::API>.
943 =head3 OPTIONAL PARAMETERS
945 All parameters to C<context> are optional.
951 If you must obtain a context in a sub deeper than your entry point you can use
952 this to tell it how many EXTRA stack frames to look back. If this option is not
953 provided the default of C<0> is used.
955 sub third_party_tool {
957 ... # Does not obtain a context
962 third_party_tool(sub {
963 my $ctx = context(level => 1);
968 =item wrapped => $int
970 Use this if you need to write your own tool that wraps a call to C<context()>
971 with the intent that it should return a context object.
974 my %params = ( wrapped => 0, @_ );
976 my $ctx = context(%params);
982 my $ctx = my_context();
987 If you do not do this, then tools you call that also check for a context will
988 notice that the context they grabbed was created at the same stack depth, which
989 will trigger protective measures that warn you and destroy the existing
992 =item stack => $stack
994 Normally C<context()> looks at the global hub stack. If you are maintaining
995 your own L<Test2::API::Stack> instance you may pass it in to be used
996 instead of the global one.
1000 Use this parameter if you want to obtain the context for a specific hub instead
1001 of whatever one happens to be at the top of the stack.
1003 =item on_init => sub { ... }
1005 This lets you provide a callback sub that will be called B<ONLY> if your call
1006 to C<context()> generated a new context. The callback B<WILL NOT> be called if
1007 C<context()> is returning an existing context. The only argument passed into
1008 the callback will be the context object itself.
1011 my $ctx = context(on_init => sub { 'will run' });
1014 # This callback is not run since we are getting the existing
1015 # context from our parent sub.
1016 my $ctx = context(on_init => sub { 'will NOT run' });
1024 =item on_release => sub { ... }
1026 This lets you provide a callback sub that will be called when the context
1027 instance is released. This callback will be added to the returned context even
1028 if an existing context is returned. If multiple calls to context add callbacks,
1029 then all will be called in reverse order when the context is finally released.
1032 my $ctx = context(on_release => sub { 'will run second' });
1035 my $ctx = context(on_release => sub { 'will run first' });
1037 # Neither callback runs on this release
1042 # Both callbacks run here.
1056 =item release $ctx, ...;
1060 This is intended as a shortcut that lets you release your context and return a
1061 value in one statement. This function will get your context, and an optional
1062 return value. It will release your context, then return your value. Scalar
1063 context is always assumed.
1066 my $ctx = context();
1069 return release $ctx, 1;
1072 This tool is most useful when you want to return the value you get from calling
1073 a function that needs to see the current context:
1075 my $ctx = context();
1076 my $out = some_tool(...);
1080 We can combine the last 3 lines of the above like so:
1082 my $ctx = context();
1083 release $ctx, some_tool(...);
1085 =head2 context_do(&;@)
1095 $ctx->ok(1, "pass");
1099 # No need to call $ctx->release, done for you on scope exit.
1103 Using this inside your test tool takes care of a lot of boilerplate for you. It
1104 will ensure a context is acquired. It will capture and rethrow any exception. It
1105 will insure the context is released when you are done. It preserves the
1106 subroutine call context (array, scalar, void).
1108 This is the safest way to write a test tool. The only two downsides to this are a
1109 slight performance decrease, and some extra indentation in your source. If the
1110 indentation is a problem for you then you can take a peek at the next section.
1112 =head2 no_context(&;$)
1118 =item no_context { ... };
1120 =item no_context { ... } $hid;
1124 my $ctx = context();
1128 # Things in here will not see our current context, they get a new
1140 This tool will hide a context for the provided block of code. This means any
1141 tools run inside the block will get a completely new context if they acquire
1142 one. The new context will be inherited by tools nested below the one that
1145 This will normally hide the current context for the top hub. If you need to
1146 hide the context for a different hub you can pass in the optional C<$hid>
1153 my $events = intercept {
1159 This function takes a codeblock as its only argument, and it has a prototype.
1160 It will execute the codeblock, intercepting any generated events in the
1161 process. It will return an array reference with all the generated event
1162 objects. All events should be subclasses of L<Test2::Event>.
1164 This is a very low-level subtest tool. This is useful for writing tools which
1165 produce subtests. This is not intended for people simply writing tests.
1167 =head2 run_subtest(...)
1171 run_subtest($NAME, \&CODE, $BUFFERED, @ARGS)
1175 run_subtest($NAME, \&CODE, \%PARAMS, @ARGS)
1177 This will run the provided codeblock with the args in C<@args>. This codeblock
1178 will be run as a subtest. A subtest is an isolated test state that is condensed
1179 into a single L<Test2::Event::Subtest> event, which contains all events
1180 generated inside the subtest.
1188 The name of the subtest.
1192 The code to run inside the subtest.
1194 =item $BUFFERED or \%PARAMS
1196 If this is a simple scalar then it will be treated as a boolean for the
1197 'buffered' setting. If this is a hash reference then it will be used as a
1198 parameters hash. The param hash will be used for hub construction (with the
1199 specified keys removed).
1201 Keys that are removed and used by run_subtest:
1205 =item 'buffered' => $bool
1207 Toggle buffered status.
1209 =item 'inherit_trace' => $bool
1211 Normally the subtest hub is pushed and the sub is allowed to generate its own
1212 root context for the hub. When this setting is turned on a root context will be
1213 created for the hub that shares the same trace as the current context.
1215 Set this to true if your tool is producing subtests without user-specified
1218 =item 'no_fork' => $bool
1220 Defaults to off. Normally forking inside a subtest will actually fork the
1221 subtest, resulting in 2 final subtest events. This parameter will turn off that
1222 behavior, only the original process/thread will return a final subtest event.
1228 Any extra arguments you want passed into the subtest code.
1232 =head3 BUFFERED VS UNBUFFERED (OR STREAMED)
1234 Normally all events inside and outside a subtest are sent to the formatter
1235 immediately by the hub. Sometimes it is desirable to hold off sending events
1236 within a subtest until the subtest is complete. This usually depends on the
1237 formatter being used.
1241 =item Things not effected by this flag
1243 In both cases events are generated and stored in an array. This array is
1244 eventually used to populate the C<subevents> attribute on the
1245 L<Test2::Event::Subtest> event that is generated at the end of the subtest.
1246 This flag has no effect on this part, it always happens.
1248 At the end of the subtest, the final L<Test2::Event::Subtest> event is sent to
1251 =item Things that are effected by this flag
1253 The C<buffered> attribute of the L<Test2::Event::Subtest> event will be set to
1254 the value of this flag. This means any formatter, listener, etc which looks at
1255 the event will know if it was buffered.
1257 =item Things that are formatter dependant
1259 Events within a buffered subtest may or may not be sent to the formatter as
1260 they happen. If a formatter fails to specify then the default is to B<NOT SEND>
1261 the events as they are generated, instead the formatter can pull them from the
1262 C<subevents> attribute.
1264 A formatter can specify by implementing the C<hide_buffered()> method. If this
1265 method returns true then events generated inside a buffered subtest will not be
1266 sent independently of the final subtest event.
1270 An example of how this is used is the L<Test2::Formatter::TAP> formatter. For
1271 unbuffered subtests the events are rendered as they are generated. At the end
1272 of the subtest, the final subtest event is rendered, but the C<subevents>
1273 attribute is ignored. For buffered subtests the opposite occurs, the events are
1274 NOT rendered as they are generated, instead the C<subevents> attribute is used
1275 to render them all at once. This is useful when running subtests tests in
1276 parallel, since without it the output from subtests would be interleaved
1279 =head1 OTHER API EXPORTS
1281 Exports in this section are not commonly needed. These all have the 'test2_'
1282 prefix to help ensure they stand out. You should look at the L</MAIN API
1283 EXPORTS> section before looking here. This section is one where "Great power
1284 comes with great responsibility". It is possible to break things badly if you
1285 are not careful with these.
1287 All exports are optional. You need to list which ones you want at import time:
1289 use Test2::API qw/test2_init_done .../;
1291 =head2 STATUS AND INITIALIZATION STATE
1293 These provide access to internal state and object instances.
1297 =item $bool = test2_init_done()
1299 This will return true if the stack and IPC instances have already been
1300 initialized. It will return false if they have not. Init happens as late as
1301 possible. It happens as soon as a tool requests the IPC instance, the
1302 formatter, or the stack.
1304 =item $bool = test2_load_done()
1306 This will simply return the boolean value of the loaded flag. If Test2 has
1307 finished loading this will be true, otherwise false. Loading is considered
1308 complete the first time a tool requests a context.
1310 =item test2_set_is_end()
1312 =item test2_set_is_end($bool)
1314 This is used to toggle Test2's belief that the END phase has already started.
1315 With no arguments this will set it to true. With arguments it will set it to
1316 the first argument's value.
1318 This is used to prevent the use of C<caller()> in END blocks which can cause
1319 segfaults. This is only necessary in some persistent environments that may have
1320 multiple END phases.
1322 =item $bool = test2_get_is_end()
1324 Check if Test2 believes it is the END phase.
1326 =item $stack = test2_stack()
1328 This will return the global L<Test2::API::Stack> instance. If this has not
1329 yet been initialized it will be initialized now.
1331 =item $bool = test2_is_testing_done()
1333 This will return true if testing is complete and no other events should be
1334 sent. This is useful in things like warning handlers where you might want to
1335 turn warnings into events, but need them to start acting like normal warnings
1336 when testing is done.
1338 $SIG{__WARN__} = sub {
1341 if (test2_is_testing_done()) {
1345 my $ctx = context();
1351 =item test2_ipc_disable
1355 =item $bool = test2_ipc_diabled
1357 Check if IPC is disabled.
1359 =item test2_ipc_wait_enable()
1361 =item test2_ipc_wait_disable()
1363 =item $bool = test2_ipc_wait_enabled()
1365 These can be used to turn IPC waiting on and off, or check the current value of
1368 Waiting is turned on by default. Waiting will cause the parent process/thread
1369 to wait until all child processes and threads are finished before exiting. You
1370 will almost never want to turn this off.
1372 =item $bool = test2_no_wait()
1374 =item test2_no_wait($bool)
1376 B<DISCOURAGED>: This is a confusing interface, it is better to use
1377 C<test2_ipc_wait_enable()>, C<test2_ipc_wait_disable()> and
1378 C<test2_ipc_wait_enabled()>.
1380 This can be used to get/set the no_wait status. Waiting is turned on by
1381 default. Waiting will cause the parent process/thread to wait until all child
1382 processes and threads are finished before exiting. You will almost never want
1385 =item $fh = test2_stdout()
1387 =item $fh = test2_stderr()
1389 These functions return the filehandles that test output should be written to.
1390 They are primarily useful when writing a custom formatter and code that turns
1391 events into actual output (TAP, etc.). They will return a dupe of the original
1392 filehandles that formatted output can be sent to regardless of whatever state
1393 the currently running test may have left STDOUT and STDERR in.
1395 =item test2_reset_io()
1397 Re-dupe the internal filehandles returned by C<test2_stdout()> and
1398 C<test2_stderr()> from the current STDOUT and STDERR. You shouldn't need to do
1399 this except in very peculiar situations (for example, you're testing a new
1400 formatter and you need control over where the formatter is sending its output.)
1404 =head2 BEHAVIOR HOOKS
1406 These are hooks that allow you to add custom behavior to actions taken by Test2
1407 and tools built on top of it.
1411 =item test2_add_callback_exit(sub { ... })
1413 This can be used to add a callback that is called after all testing is done. This
1414 is too late to add additional results, the main use of this callback is to set the
1417 test2_add_callback_exit(
1419 my ($context, $exit, \$new_exit) = @_;
1424 The C<$context> passed in will be an instance of L<Test2::API::Context>. The
1425 C<$exit> argument will be the original exit code before anything modified it.
1426 C<$$new_exit> is a reference to the new exit code. You may modify this to
1427 change the exit code. Please note that C<$$new_exit> may already be different
1430 =item test2_add_callback_post_load(sub { ... })
1432 Add a callback that will be called when Test2 is finished loading. This
1433 means the callback will be run once, the first time a context is obtained.
1434 If Test2 has already finished loading then the callback will be run immediately.
1436 =item test2_add_callback_testing_done(sub { ... })
1438 This adds your coderef as a follow-up to the root hub after Test2 is finished loading.
1440 This is essentially a helper to do the following:
1442 test2_add_callback_post_load(sub {
1443 my $stack = test2_stack();
1444 $stack->top; # Insure we have a hub
1445 my ($hub) = Test2::API::test2_stack->all;
1447 $hub->set_active(1);
1449 $hub->follow_up(sub { ... }); # <-- Your coderef here
1452 =item test2_add_callback_context_acquire(sub { ... })
1454 Add a callback that will be called every time someone tries to acquire a
1455 context. This will be called on EVERY call to C<context()>. It gets a single
1456 argument, a reference to the hash of parameters being used the construct the
1457 context. This is your chance to change the parameters by directly altering the
1460 test2_add_callback_context_acquire(sub {
1465 This is a very scary API function. Please do not use this unless you need to.
1466 This is here for L<Test::Builder> and backwards compatibility. This has you
1467 directly manipulate the hash instead of returning a new one for performance
1470 =item test2_add_callback_context_init(sub { ... })
1472 Add a callback that will be called every time a new context is created. The
1473 callback will receive the newly created context as its only argument.
1475 =item test2_add_callback_context_release(sub { ... })
1477 Add a callback that will be called every time a context is released. The
1478 callback will receive the released context as its only argument.
1480 =item test2_add_callback_pre_subtest(sub { ... })
1482 Add a callback that will be called every time a subtest is going to be
1483 run. The callback will receive the subtest name, coderef, and any
1486 =item @list = test2_list_context_acquire_callbacks()
1488 Return all the context acquire callback references.
1490 =item @list = test2_list_context_init_callbacks()
1492 Returns all the context init callback references.
1494 =item @list = test2_list_context_release_callbacks()
1496 Returns all the context release callback references.
1498 =item @list = test2_list_exit_callbacks()
1500 Returns all the exit callback references.
1502 =item @list = test2_list_post_load_callbacks()
1504 Returns all the post load callback references.
1506 =item @list = test2_list_pre_subtest_callbacks()
1508 Returns all the pre-subtest callback references.
1510 =item test2_add_uuid_via(sub { ... })
1512 =item $sub = test2_add_uuid_via()
1514 This allows you to provide a UUID generator. If provided UUIDs will be attached
1515 to all events, hubs, and contexts. This is useful for storing, tracking, and
1516 linking these objects.
1518 The sub you provide should always return a unique identifier. Most things will
1519 expect a proper UUID string, however nothing in Test2::API enforces this.
1521 The sub will receive exactly 1 argument, the type of thing being tagged
1522 'context', 'hub', or 'event'. In the future additional things may be tagged, in
1523 which case new strings will be passed in. These are purely informative, you can
1524 (and usually should) ignore them.
1528 =head2 IPC AND CONCURRENCY
1530 These let you access, or specify, the IPC system internals.
1534 =item $bool = test2_has_ipc()
1536 Check if IPC is enabled.
1538 =item $ipc = test2_ipc()
1540 This will return the global L<Test2::IPC::Driver> instance. If this has not yet
1541 been initialized it will be initialized now.
1543 =item test2_ipc_add_driver($DRIVER)
1545 Add an IPC driver to the list. This will add the driver to the start of the
1548 =item @drivers = test2_ipc_drivers()
1550 Get the list of IPC drivers.
1552 =item $bool = test2_ipc_polling()
1554 Check if polling is enabled.
1556 =item test2_ipc_enable_polling()
1558 Turn on polling. This will cull events from other processes and threads every
1559 time a context is created.
1561 =item test2_ipc_disable_polling()
1563 Turn off IPC polling.
1565 =item test2_ipc_enable_shm()
1567 Legacy, this is currently a no-op that returns 0;
1569 =item test2_ipc_set_pending($uniq_val)
1571 Tell other processes and events that an event is pending. C<$uniq_val> should
1572 be a unique value no other thread/process will generate.
1574 B<Note:> After calling this C<test2_ipc_get_pending()> will return 1. This is
1575 intentional, and not avoidable.
1577 =item $pending = test2_ipc_get_pending()
1579 This returns -1 if there is no way to check (assume yes)
1581 This returns 0 if there are (most likely) no pending events.
1583 This returns 1 if there are (likely) pending events. Upon return it will reset,
1584 nothing else will be able to see that there were pending events.
1586 =item $timeout = test2_ipc_get_timeout()
1588 =item test2_ipc_set_timeout($timeout)
1590 Get/Set the timeout value for the IPC system. This timeout is how long the IPC
1591 system will wait for child processes and threads to finish before aborting.
1593 The default value is C<30> seconds.
1597 =head2 MANAGING FORMATTERS
1599 These let you access, or specify, the formatters that can/should be used.
1603 =item $formatter = test2_formatter
1605 This will return the global formatter class. This is not an instance. By
1606 default the formatter is set to L<Test2::Formatter::TAP>.
1608 You can override this default using the C<T2_FORMATTER> environment variable.
1610 Normally 'Test2::Formatter::' is prefixed to the value in the
1611 environment variable:
1613 $ T2_FORMATTER='TAP' perl test.t # Use the Test2::Formatter::TAP formatter
1614 $ T2_FORMATTER='Foo' perl test.t # Use the Test2::Formatter::Foo formatter
1616 If you want to specify a full module name you use the '+' prefix:
1618 $ T2_FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter
1620 =item test2_formatter_set($class_or_instance)
1622 Set the global formatter class. This can only be set once. B<Note:> This will
1623 override anything specified in the 'T2_FORMATTER' environment variable.
1625 =item @formatters = test2_formatters()
1627 Get a list of all loaded formatters.
1629 =item test2_formatter_add($class_or_instance)
1631 Add a formatter to the list. Last formatter added is used at initialization. If
1632 this is called after initialization a warning will be issued.
1636 =head1 OTHER EXAMPLES
1638 See the C</Examples/> directory included in this distribution.
1642 L<Test2::API::Context> - Detailed documentation of the context object.
1644 L<Test2::IPC> - The IPC system used for threading/fork support.
1646 L<Test2::Formatter> - Formatters such as TAP live here.
1648 L<Test2::Event> - Events live in this namespace.
1650 L<Test2::Hub> - All events eventually funnel through a hub. Custom hubs are how
1651 C<intercept()> and C<run_subtest()> are implemented.
1655 This package has an END block. This END block is responsible for setting the
1656 exit code based on the test results. This end block also calls the callbacks that
1657 can be added to this package.
1661 The source code repository for Test2 can be found at
1662 F<http://github.com/Test-More/test-more/>.
1668 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
1676 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
1682 Copyright 2019 Chad Granum E<lt>exodist@cpan.orgE<gt>.
1684 This program is free software; you can redistribute it and/or
1685 modify it under the same terms as Perl itself.
1687 See F<http://dev.perl.org/licenses/>