5 use Test2::Util qw/USE_THREADS/;
8 $ENV{TEST_ACTIVE} ||= 1;
9 $ENV{TEST2_ACTIVE} = 1;
12 our $VERSION = '1.302183';
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, @other) = $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, @other) = 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},
463 full_caller => [$pkg, $file, $line, $sub, @other],
466 huuid => $hub->{uuid},
467 uuid => ${$UUID_VIA}->('context'),
470 'Test2::EventFacet::Trace'
473 # Directly bless the object here, calling new is a noticeable performance
474 # hit with how often this needs to be called.
478 _aborted => \$aborted,
485 eval_error => $eval_error,
486 child_error => $child_error,
487 $params{on_release} ? (_on_release => [$params{on_release}]) : (),
489 'Test2::API::Context'
492 $CONTEXTS->{$hid} = $current;
493 weaken($CONTEXTS->{$hid});
495 $_->($current) for @$INIT_CBS;
496 map $_->($current), @{$hub->{_context_init}} if $hub->{_context_init};
498 $params{on_init}->($current) if $params{on_init};
500 ($!, $@, $?, $^E) = ($errno, $eval_error, $child_error, $extended_error);
506 _existing_error(@_, <<" EOT");
507 context() was called to retrieve an existing context, however the existing
508 context was created in a stack frame at the same, or deeper level. This usually
509 means that a tool failed to release the context when it was finished.
514 _existing_error(@_, <<" EOT");
515 context() was called to retrieve an existing context, however the existing
516 context has an invalid internal state (!_canon_count). This should not normally
517 happen unless something is mucking about with internals...
521 sub _existing_error {
522 my ($ctx, $details, $msg) = @_;
523 my ($pkg, $file, $line, $sub, $depth) = @$details;
525 my $oldframe = $ctx->{trace}->frame;
526 my $olddepth = $ctx->{_depth};
528 # Older versions of Carp do not export longmess() function, so it needs to be called with package name
529 my $mess = Carp::longmess();
547 Removing the old context and creating a new one...
560 my $events = _intercept($code, deep => 0);
567 sub intercept_deep(&) {
571 my $events = _intercept($code, deep => 1);
584 if (my $global_ipc = test2_ipc()) {
585 my $driver = blessed($global_ipc);
589 my $hub = Test2::Hub::Interceptor->new(
595 $hub->listen(sub { push @events => $_[1] }, inherit => $params{deep});
597 $ctx->stack->top; # Make sure there is a top hub before we begin.
598 $ctx->stack->push($hub);
600 my $trace = $ctx->trace;
602 $hub->clean_inherited(trace => $trace, state => $state);
604 my ($ok, $err) = (1, undef);
605 T2_SUBTEST_WRAPPER: {
606 # Do not use 'try' cause it localizes __DIE__
607 $ok = eval { $code->(hub => $hub, context => $ctx->snapshot); 1 };
610 # They might have done 'BEGIN { skip_all => "whatever" }'
611 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && $err->isa('Test2::Hub::Interceptor::Terminator'))) {
618 $ctx->stack->pop($hub);
620 $hub->restore_inherited(trace => $trace, state => $state);
626 $hub->finalize($trace, 1)
631 require Test2::API::InterceptResult;
632 return Test2::API::InterceptResult->new_from_ref(\@events);
636 my ($name, $code, $params, @args) = @_;
638 $_->($name,$code,@args)
639 for Test2::API::test2_list_pre_subtest_callbacks();
641 $params = {buffered => $params} unless ref $params;
642 my $inherit_trace = delete $params->{inherit_trace};
646 my $parent = $ctx->hub;
648 # If a parent is buffered then the child must be as well.
649 my $buffered = $params->{buffered} || $parent->{buffered};
651 $ctx->note($name) unless $buffered;
653 my $stack = $ctx->stack || $STACK;
654 my $hub = $stack->new_hub(
655 class => 'Test2::Hub::Subtest',
657 buffered => $buffered,
661 $hub->listen(sub { push @events => $_[1] });
664 if (my $format = $hub->format) {
665 my $hide = $format->can('hide_buffered') ? $format->hide_buffered : 1;
666 $hub->format(undef) if $hide;
670 if ($inherit_trace) {
673 my $base_trace = $ctx->trace;
674 my $trace = $base_trace->snapshot(nested => 1 + $base_trace->nested);
675 my $st_ctx = Test2::API::Context->new(
679 $st_ctx->do_in_context($orig, @args);
683 my ($ok, $err, $finished);
684 T2_SUBTEST_WRAPPER: {
685 # Do not use 'try' cause it localizes __DIE__
686 $ok = eval { $code->(@args); 1 };
689 # They might have done 'BEGIN { skip_all => "whatever" }'
690 if (!$ok && $err =~ m/Label not found for "last T2_SUBTEST_WRAPPER"/ || (blessed($err) && blessed($err) eq 'Test::Builder::Exception')) {
699 if ($params->{no_fork}) {
700 if ($$ != $ctx->trace->pid) {
701 warn $ok ? "Forked inside subtest, but subtest never finished!\n" : $err;
705 if (get_tid() != $ctx->trace->tid) {
706 warn $ok ? "Started new thread inside subtest, but thread never finished!\n" : $err;
710 elsif (!$parent->is_local && !$parent->ipc) {
711 warn $ok ? "A new process or thread was started inside subtest, but IPC is not enabled!\n" : $err;
717 my $trace = $ctx->trace;
719 my $bailed = $hub->bailed_out;
722 if ($bailed && !$buffered) {
723 $ctx->bail($bailed->reason);
725 elsif ($bailed && $buffered) {
729 my $code = $hub->exit_code;
731 $err = "Subtest ended with exit code $code" if $code;
735 $hub->finalize($trace->snapshot(huuid => $hub->uuid, hid => $hub->hid, nested => $hub->nested, buffered => $buffered), 1)
740 my $pass = $ok && $hub->is_passing;
741 my $e = $ctx->build_event(
745 subtest_id => $hub->id,
746 subtest_uuid => $hub->uuid,
747 buffered => $buffered,
748 subevents => \@events,
751 my $plan_ok = $hub->check_plan;
755 $ctx->failure_diag($e) unless $e->pass;
757 $ctx->diag("Caught exception in subtest: $err") unless $ok;
759 $ctx->diag("Bad subtest plan, expected " . $hub->plan . " but ran " . $hub->count)
760 if defined($plan_ok) && !$plan_ok;
762 $ctx->bail($bailed->reason) if $bailed && $buffered;
768 # There is a use-cycle between API and API/Context. Context needs to use some
769 # API functions as the package is compiling. Test2::API::context() needs
770 # Test2::API::Context to be loaded, but we cannot 'require' the module there as
771 # it causes a very noticeable performance impact with how often context() is
773 require Test2::API::Context;
785 Test2::API - Primary interface for writing Test2 based testing tools.
787 =head1 ***INTERNALS NOTE***
789 B<The internals of this package are subject to change at any time!> The public
790 methods provided will not change in backwards-incompatible ways (once there is
791 a stable release), but the underlying implementation details might.
792 B<Do not break encapsulation here!>
794 Currently the implementation is to create a single instance of the
795 L<Test2::API::Instance> Object. All class methods defer to the single
796 instance. There is no public access to the singleton, and that is intentional.
797 The class methods provided by this package provide the only functionality
800 This is done primarily to avoid the problems Test::Builder had by exposing its
801 singleton. We do not want anyone to replace this singleton, rebless it, or
802 directly muck with its internals. If you need to do something and cannot
803 because of the restrictions placed here, then please report it as an issue. If
804 possible, we will create a way for you to implement your functionality without
805 exposing things that should not be exposed.
809 This package exports all the functions necessary to write and/or verify testing
810 tools. Using these building blocks you can begin writing test tools very
811 quickly. You are also provided with tools that help you to test the tools you
816 =head2 WRITING A TOOL
818 The C<context()> method is your primary interface into the Test2 framework.
821 use Test2::API qw/context/;
823 our @EXPORT = qw/my_ok/;
826 # Just like ok() from Test::More
828 my ($bool, $name) = @_;
829 my $ctx = context(); # Get a context
830 $ctx->ok($bool, $name);
831 $ctx->release; # Release the context
835 See L<Test2::API::Context> for a list of methods available on the context object.
837 =head2 TESTING YOUR TOOLS
839 The C<intercept { ... }> tool lets you temporarily intercept all events
840 generated by the test system:
842 use Test2::API qw/intercept/;
844 use My::Ok qw/my_ok/;
846 my $events = intercept {
847 # These events are not displayed
852 As of version 1.302178 this now returns an arrayref that is also an instance of
853 L<Test2::API::InterceptResult>. See the L<Test2::API::InterceptResult>
854 documentation for details on how to best use it.
856 =head2 OTHER API FUNCTIONS
866 test2_is_testing_done
869 my $init = test2_init_done();
870 my $stack = test2_stack();
871 my $ipc = test2_ipc();
873 test2_formatter_set($FORMATTER)
874 my $formatter = test2_formatter();
878 =head1 MAIN API EXPORTS
880 All exports are optional. You must specify subs to import.
882 use Test2::API qw/context intercept run_subtest/;
884 This is the list of exports that are most commonly needed. If you are simply
885 writing a tool, then this is probably all you need. If you need something and
886 you cannot find it here, then you can also look at L</OTHER API EXPORTS>.
888 These exports lack the 'test2_' prefix because of how important/common they
889 are. Exports in the L</OTHER API EXPORTS> section have the 'test2_' prefix to
890 ensure they stand out.
898 =item $ctx = context()
900 =item $ctx = context(%params)
904 The C<context()> function will always return the current context. If
905 there is already a context active, it will be returned. If there is not an
906 active context, one will be generated. When a context is generated it will
907 default to using the file and line number where the currently running sub was
910 Please see L<Test2::API::Context/"CRITICAL DETAILS"> for important rules about
911 what you can and cannot do with a context once it is obtained.
913 B<Note> This function will throw an exception if you ignore the context object
916 B<Note> On perls 5.14+ a depth check is used to insure there are no context
917 leaks. This cannot be safely done on older perls due to
918 L<https://rt.perl.org/Public/Bug/Display.html?id=127774>
919 You can forcefully enable it either by setting C<$ENV{T2_CHECK_DEPTH} = 1> or
920 C<$Test2::API::DO_DEPTH_CHECK = 1> B<BEFORE> loading L<Test2::API>.
922 =head3 OPTIONAL PARAMETERS
924 All parameters to C<context> are optional.
930 If you must obtain a context in a sub deeper than your entry point you can use
931 this to tell it how many EXTRA stack frames to look back. If this option is not
932 provided the default of C<0> is used.
934 sub third_party_tool {
936 ... # Does not obtain a context
941 third_party_tool(sub {
942 my $ctx = context(level => 1);
947 =item wrapped => $int
949 Use this if you need to write your own tool that wraps a call to C<context()>
950 with the intent that it should return a context object.
953 my %params = ( wrapped => 0, @_ );
955 my $ctx = context(%params);
961 my $ctx = my_context();
966 If you do not do this, then tools you call that also check for a context will
967 notice that the context they grabbed was created at the same stack depth, which
968 will trigger protective measures that warn you and destroy the existing
971 =item stack => $stack
973 Normally C<context()> looks at the global hub stack. If you are maintaining
974 your own L<Test2::API::Stack> instance you may pass it in to be used
975 instead of the global one.
979 Use this parameter if you want to obtain the context for a specific hub instead
980 of whatever one happens to be at the top of the stack.
982 =item on_init => sub { ... }
984 This lets you provide a callback sub that will be called B<ONLY> if your call
985 to C<context()> generated a new context. The callback B<WILL NOT> be called if
986 C<context()> is returning an existing context. The only argument passed into
987 the callback will be the context object itself.
990 my $ctx = context(on_init => sub { 'will run' });
993 # This callback is not run since we are getting the existing
994 # context from our parent sub.
995 my $ctx = context(on_init => sub { 'will NOT run' });
1003 =item on_release => sub { ... }
1005 This lets you provide a callback sub that will be called when the context
1006 instance is released. This callback will be added to the returned context even
1007 if an existing context is returned. If multiple calls to context add callbacks,
1008 then all will be called in reverse order when the context is finally released.
1011 my $ctx = context(on_release => sub { 'will run second' });
1014 my $ctx = context(on_release => sub { 'will run first' });
1016 # Neither callback runs on this release
1021 # Both callbacks run here.
1035 =item release $ctx, ...;
1039 This is intended as a shortcut that lets you release your context and return a
1040 value in one statement. This function will get your context, and an optional
1041 return value. It will release your context, then return your value. Scalar
1042 context is always assumed.
1045 my $ctx = context();
1048 return release $ctx, 1;
1051 This tool is most useful when you want to return the value you get from calling
1052 a function that needs to see the current context:
1054 my $ctx = context();
1055 my $out = some_tool(...);
1059 We can combine the last 3 lines of the above like so:
1061 my $ctx = context();
1062 release $ctx, some_tool(...);
1064 =head2 context_do(&;@)
1074 $ctx->ok(1, "pass");
1078 # No need to call $ctx->release, done for you on scope exit.
1082 Using this inside your test tool takes care of a lot of boilerplate for you. It
1083 will ensure a context is acquired. It will capture and rethrow any exception. It
1084 will insure the context is released when you are done. It preserves the
1085 subroutine call context (array, scalar, void).
1087 This is the safest way to write a test tool. The only two downsides to this are a
1088 slight performance decrease, and some extra indentation in your source. If the
1089 indentation is a problem for you then you can take a peek at the next section.
1091 =head2 no_context(&;$)
1097 =item no_context { ... };
1099 =item no_context { ... } $hid;
1103 my $ctx = context();
1107 # Things in here will not see our current context, they get a new
1119 This tool will hide a context for the provided block of code. This means any
1120 tools run inside the block will get a completely new context if they acquire
1121 one. The new context will be inherited by tools nested below the one that
1124 This will normally hide the current context for the top hub. If you need to
1125 hide the context for a different hub you can pass in the optional C<$hid>
1132 my $events = intercept {
1138 This function takes a codeblock as its only argument, and it has a prototype.
1139 It will execute the codeblock, intercepting any generated events in the
1140 process. It will return an array reference with all the generated event
1141 objects. All events should be subclasses of L<Test2::Event>.
1143 As of version 1.302178 the events array that is returned is blssed as an
1144 L<Test2::API::InterceptResult> instance. L<Test2::API::InterceptResult>
1145 Provides a helpful interface for filtering and/or inspecting the events list
1146 overall, or individual events within the list.
1148 This is intended to help you test your test code. This is not intended for
1149 people simply writing tests.
1151 =head2 run_subtest(...)
1155 run_subtest($NAME, \&CODE, $BUFFERED, @ARGS)
1159 run_subtest($NAME, \&CODE, \%PARAMS, @ARGS)
1161 This will run the provided codeblock with the args in C<@args>. This codeblock
1162 will be run as a subtest. A subtest is an isolated test state that is condensed
1163 into a single L<Test2::Event::Subtest> event, which contains all events
1164 generated inside the subtest.
1172 The name of the subtest.
1176 The code to run inside the subtest.
1178 =item $BUFFERED or \%PARAMS
1180 If this is a simple scalar then it will be treated as a boolean for the
1181 'buffered' setting. If this is a hash reference then it will be used as a
1182 parameters hash. The param hash will be used for hub construction (with the
1183 specified keys removed).
1185 Keys that are removed and used by run_subtest:
1189 =item 'buffered' => $bool
1191 Toggle buffered status.
1193 =item 'inherit_trace' => $bool
1195 Normally the subtest hub is pushed and the sub is allowed to generate its own
1196 root context for the hub. When this setting is turned on a root context will be
1197 created for the hub that shares the same trace as the current context.
1199 Set this to true if your tool is producing subtests without user-specified
1202 =item 'no_fork' => $bool
1204 Defaults to off. Normally forking inside a subtest will actually fork the
1205 subtest, resulting in 2 final subtest events. This parameter will turn off that
1206 behavior, only the original process/thread will return a final subtest event.
1212 Any extra arguments you want passed into the subtest code.
1216 =head3 BUFFERED VS UNBUFFERED (OR STREAMED)
1218 Normally all events inside and outside a subtest are sent to the formatter
1219 immediately by the hub. Sometimes it is desirable to hold off sending events
1220 within a subtest until the subtest is complete. This usually depends on the
1221 formatter being used.
1225 =item Things not effected by this flag
1227 In both cases events are generated and stored in an array. This array is
1228 eventually used to populate the C<subevents> attribute on the
1229 L<Test2::Event::Subtest> event that is generated at the end of the subtest.
1230 This flag has no effect on this part, it always happens.
1232 At the end of the subtest, the final L<Test2::Event::Subtest> event is sent to
1235 =item Things that are effected by this flag
1237 The C<buffered> attribute of the L<Test2::Event::Subtest> event will be set to
1238 the value of this flag. This means any formatter, listener, etc which looks at
1239 the event will know if it was buffered.
1241 =item Things that are formatter dependant
1243 Events within a buffered subtest may or may not be sent to the formatter as
1244 they happen. If a formatter fails to specify then the default is to B<NOT SEND>
1245 the events as they are generated, instead the formatter can pull them from the
1246 C<subevents> attribute.
1248 A formatter can specify by implementing the C<hide_buffered()> method. If this
1249 method returns true then events generated inside a buffered subtest will not be
1250 sent independently of the final subtest event.
1254 An example of how this is used is the L<Test2::Formatter::TAP> formatter. For
1255 unbuffered subtests the events are rendered as they are generated. At the end
1256 of the subtest, the final subtest event is rendered, but the C<subevents>
1257 attribute is ignored. For buffered subtests the opposite occurs, the events are
1258 NOT rendered as they are generated, instead the C<subevents> attribute is used
1259 to render them all at once. This is useful when running subtests tests in
1260 parallel, since without it the output from subtests would be interleaved
1263 =head1 OTHER API EXPORTS
1265 Exports in this section are not commonly needed. These all have the 'test2_'
1266 prefix to help ensure they stand out. You should look at the L</MAIN API
1267 EXPORTS> section before looking here. This section is one where "Great power
1268 comes with great responsibility". It is possible to break things badly if you
1269 are not careful with these.
1271 All exports are optional. You need to list which ones you want at import time:
1273 use Test2::API qw/test2_init_done .../;
1275 =head2 STATUS AND INITIALIZATION STATE
1277 These provide access to internal state and object instances.
1281 =item $bool = test2_init_done()
1283 This will return true if the stack and IPC instances have already been
1284 initialized. It will return false if they have not. Init happens as late as
1285 possible. It happens as soon as a tool requests the IPC instance, the
1286 formatter, or the stack.
1288 =item $bool = test2_load_done()
1290 This will simply return the boolean value of the loaded flag. If Test2 has
1291 finished loading this will be true, otherwise false. Loading is considered
1292 complete the first time a tool requests a context.
1294 =item test2_set_is_end()
1296 =item test2_set_is_end($bool)
1298 This is used to toggle Test2's belief that the END phase has already started.
1299 With no arguments this will set it to true. With arguments it will set it to
1300 the first argument's value.
1302 This is used to prevent the use of C<caller()> in END blocks which can cause
1303 segfaults. This is only necessary in some persistent environments that may have
1304 multiple END phases.
1306 =item $bool = test2_get_is_end()
1308 Check if Test2 believes it is the END phase.
1310 =item $stack = test2_stack()
1312 This will return the global L<Test2::API::Stack> instance. If this has not
1313 yet been initialized it will be initialized now.
1315 =item $bool = test2_is_testing_done()
1317 This will return true if testing is complete and no other events should be
1318 sent. This is useful in things like warning handlers where you might want to
1319 turn warnings into events, but need them to start acting like normal warnings
1320 when testing is done.
1322 $SIG{__WARN__} = sub {
1325 if (test2_is_testing_done()) {
1329 my $ctx = context();
1335 =item test2_ipc_disable
1339 =item $bool = test2_ipc_diabled
1341 Check if IPC is disabled.
1343 =item test2_ipc_wait_enable()
1345 =item test2_ipc_wait_disable()
1347 =item $bool = test2_ipc_wait_enabled()
1349 These can be used to turn IPC waiting on and off, or check the current value of
1352 Waiting is turned on by default. Waiting will cause the parent process/thread
1353 to wait until all child processes and threads are finished before exiting. You
1354 will almost never want to turn this off.
1356 =item $bool = test2_no_wait()
1358 =item test2_no_wait($bool)
1360 B<DISCOURAGED>: This is a confusing interface, it is better to use
1361 C<test2_ipc_wait_enable()>, C<test2_ipc_wait_disable()> and
1362 C<test2_ipc_wait_enabled()>.
1364 This can be used to get/set the no_wait status. Waiting is turned on by
1365 default. Waiting will cause the parent process/thread to wait until all child
1366 processes and threads are finished before exiting. You will almost never want
1369 =item $fh = test2_stdout()
1371 =item $fh = test2_stderr()
1373 These functions return the filehandles that test output should be written to.
1374 They are primarily useful when writing a custom formatter and code that turns
1375 events into actual output (TAP, etc.). They will return a dupe of the original
1376 filehandles that formatted output can be sent to regardless of whatever state
1377 the currently running test may have left STDOUT and STDERR in.
1379 =item test2_reset_io()
1381 Re-dupe the internal filehandles returned by C<test2_stdout()> and
1382 C<test2_stderr()> from the current STDOUT and STDERR. You shouldn't need to do
1383 this except in very peculiar situations (for example, you're testing a new
1384 formatter and you need control over where the formatter is sending its output.)
1388 =head2 BEHAVIOR HOOKS
1390 These are hooks that allow you to add custom behavior to actions taken by Test2
1391 and tools built on top of it.
1395 =item test2_add_callback_exit(sub { ... })
1397 This can be used to add a callback that is called after all testing is done. This
1398 is too late to add additional results, the main use of this callback is to set the
1401 test2_add_callback_exit(
1403 my ($context, $exit, \$new_exit) = @_;
1408 The C<$context> passed in will be an instance of L<Test2::API::Context>. The
1409 C<$exit> argument will be the original exit code before anything modified it.
1410 C<$$new_exit> is a reference to the new exit code. You may modify this to
1411 change the exit code. Please note that C<$$new_exit> may already be different
1414 =item test2_add_callback_post_load(sub { ... })
1416 Add a callback that will be called when Test2 is finished loading. This
1417 means the callback will be run once, the first time a context is obtained.
1418 If Test2 has already finished loading then the callback will be run immediately.
1420 =item test2_add_callback_testing_done(sub { ... })
1422 This adds your coderef as a follow-up to the root hub after Test2 is finished loading.
1424 This is essentially a helper to do the following:
1426 test2_add_callback_post_load(sub {
1427 my $stack = test2_stack();
1428 $stack->top; # Insure we have a hub
1429 my ($hub) = Test2::API::test2_stack->all;
1431 $hub->set_active(1);
1433 $hub->follow_up(sub { ... }); # <-- Your coderef here
1436 =item test2_add_callback_context_acquire(sub { ... })
1438 Add a callback that will be called every time someone tries to acquire a
1439 context. This will be called on EVERY call to C<context()>. It gets a single
1440 argument, a reference to the hash of parameters being used the construct the
1441 context. This is your chance to change the parameters by directly altering the
1444 test2_add_callback_context_acquire(sub {
1449 This is a very scary API function. Please do not use this unless you need to.
1450 This is here for L<Test::Builder> and backwards compatibility. This has you
1451 directly manipulate the hash instead of returning a new one for performance
1454 =item test2_add_callback_context_init(sub { ... })
1456 Add a callback that will be called every time a new context is created. The
1457 callback will receive the newly created context as its only argument.
1459 =item test2_add_callback_context_release(sub { ... })
1461 Add a callback that will be called every time a context is released. The
1462 callback will receive the released context as its only argument.
1464 =item test2_add_callback_pre_subtest(sub { ... })
1466 Add a callback that will be called every time a subtest is going to be
1467 run. The callback will receive the subtest name, coderef, and any
1470 =item @list = test2_list_context_acquire_callbacks()
1472 Return all the context acquire callback references.
1474 =item @list = test2_list_context_init_callbacks()
1476 Returns all the context init callback references.
1478 =item @list = test2_list_context_release_callbacks()
1480 Returns all the context release callback references.
1482 =item @list = test2_list_exit_callbacks()
1484 Returns all the exit callback references.
1486 =item @list = test2_list_post_load_callbacks()
1488 Returns all the post load callback references.
1490 =item @list = test2_list_pre_subtest_callbacks()
1492 Returns all the pre-subtest callback references.
1494 =item test2_add_uuid_via(sub { ... })
1496 =item $sub = test2_add_uuid_via()
1498 This allows you to provide a UUID generator. If provided UUIDs will be attached
1499 to all events, hubs, and contexts. This is useful for storing, tracking, and
1500 linking these objects.
1502 The sub you provide should always return a unique identifier. Most things will
1503 expect a proper UUID string, however nothing in Test2::API enforces this.
1505 The sub will receive exactly 1 argument, the type of thing being tagged
1506 'context', 'hub', or 'event'. In the future additional things may be tagged, in
1507 which case new strings will be passed in. These are purely informative, you can
1508 (and usually should) ignore them.
1512 =head2 IPC AND CONCURRENCY
1514 These let you access, or specify, the IPC system internals.
1518 =item $bool = test2_has_ipc()
1520 Check if IPC is enabled.
1522 =item $ipc = test2_ipc()
1524 This will return the global L<Test2::IPC::Driver> instance. If this has not yet
1525 been initialized it will be initialized now.
1527 =item test2_ipc_add_driver($DRIVER)
1529 Add an IPC driver to the list. This will add the driver to the start of the
1532 =item @drivers = test2_ipc_drivers()
1534 Get the list of IPC drivers.
1536 =item $bool = test2_ipc_polling()
1538 Check if polling is enabled.
1540 =item test2_ipc_enable_polling()
1542 Turn on polling. This will cull events from other processes and threads every
1543 time a context is created.
1545 =item test2_ipc_disable_polling()
1547 Turn off IPC polling.
1549 =item test2_ipc_enable_shm()
1551 Legacy, this is currently a no-op that returns 0;
1553 =item test2_ipc_set_pending($uniq_val)
1555 Tell other processes and events that an event is pending. C<$uniq_val> should
1556 be a unique value no other thread/process will generate.
1558 B<Note:> After calling this C<test2_ipc_get_pending()> will return 1. This is
1559 intentional, and not avoidable.
1561 =item $pending = test2_ipc_get_pending()
1563 This returns -1 if there is no way to check (assume yes)
1565 This returns 0 if there are (most likely) no pending events.
1567 This returns 1 if there are (likely) pending events. Upon return it will reset,
1568 nothing else will be able to see that there were pending events.
1570 =item $timeout = test2_ipc_get_timeout()
1572 =item test2_ipc_set_timeout($timeout)
1574 Get/Set the timeout value for the IPC system. This timeout is how long the IPC
1575 system will wait for child processes and threads to finish before aborting.
1577 The default value is C<30> seconds.
1581 =head2 MANAGING FORMATTERS
1583 These let you access, or specify, the formatters that can/should be used.
1587 =item $formatter = test2_formatter
1589 This will return the global formatter class. This is not an instance. By
1590 default the formatter is set to L<Test2::Formatter::TAP>.
1592 You can override this default using the C<T2_FORMATTER> environment variable.
1594 Normally 'Test2::Formatter::' is prefixed to the value in the
1595 environment variable:
1597 $ T2_FORMATTER='TAP' perl test.t # Use the Test2::Formatter::TAP formatter
1598 $ T2_FORMATTER='Foo' perl test.t # Use the Test2::Formatter::Foo formatter
1600 If you want to specify a full module name you use the '+' prefix:
1602 $ T2_FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter
1604 =item test2_formatter_set($class_or_instance)
1606 Set the global formatter class. This can only be set once. B<Note:> This will
1607 override anything specified in the 'T2_FORMATTER' environment variable.
1609 =item @formatters = test2_formatters()
1611 Get a list of all loaded formatters.
1613 =item test2_formatter_add($class_or_instance)
1615 Add a formatter to the list. Last formatter added is used at initialization. If
1616 this is called after initialization a warning will be issued.
1620 =head1 OTHER EXAMPLES
1622 See the C</Examples/> directory included in this distribution.
1626 L<Test2::API::Context> - Detailed documentation of the context object.
1628 L<Test2::IPC> - The IPC system used for threading/fork support.
1630 L<Test2::Formatter> - Formatters such as TAP live here.
1632 L<Test2::Event> - Events live in this namespace.
1634 L<Test2::Hub> - All events eventually funnel through a hub. Custom hubs are how
1635 C<intercept()> and C<run_subtest()> are implemented.
1639 This package has an END block. This END block is responsible for setting the
1640 exit code based on the test results. This end block also calls the callbacks that
1641 can be added to this package.
1645 The source code repository for Test2 can be found at
1646 F<http://github.com/Test-More/test-more/>.
1652 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
1660 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
1666 Copyright 2020 Chad Granum E<lt>exodist@cpan.orgE<gt>.
1668 This program is free software; you can redistribute it and/or
1669 modify it under the same terms as Perl itself.
1671 See F<http://dev.perl.org/licenses/>