Currently the implementation is to create a single instance of the Test2::API::Instance Object. All class methods defer to the single instance. There is no public access to the singleton, and that is intentional. The class methods provided by this package provide the only functionality publicly exposed.
This is done primarily to avoid the problems Test::Builder had by exposing its singleton. We do not want anyone to replace this singleton, rebless it, or directly muck with its internals. If you need to do something and cannot because of the restrictions placed here, then please report it as an issue. If possible, we will create a way for you to implement your functionality without exposing things that should not be exposed.
package My::Ok;
use Test2::API qw/context/;
our @EXPORT = qw/my_ok/;
use base 'Exporter';
# Just like ok() from Test::More
sub my_ok($;$) {
my ($bool, $name) = @_;
my $ctx = context(); # Get a context
$ctx->ok($bool, $name);
$ctx->release; # Release the context
return $bool;
}
See Test2::API::Context for a list of methods available on the context object.
use Test2::API qw/intercept/;
use My::Ok qw/my_ok/;
my $events = intercept {
# These events are not displayed
my_ok(1, "pass");
my_ok(0, "fail");
};
my_ok(@$events == 2, "got 2 events, the pass and the fail");
my_ok($events->[0]->pass, "first event passed");
my_ok(!$events->[1]->pass, "second event failed");
DEEP EVENT INTERCEPTION
Normally "intercept { ... }" only intercepts events sent to the main hub (as added by intercept itself). Nested hubs, such as those created by subtests, will not be intercepted. This is normally what you will still see the nested events by inspecting the subtest event. However there are times where you want to verify each event as it is sent, in that case use "intercept_deep { ... }".
my $events = intercept_Deep {
buffered_subtest foo => sub {
ok(1, "pass");
};
};
$events in this case will contain 3 items:
This lets you see the order in which the events were sent, unlike "intercept { ... }" which only lets you see events as the main hub sees them.
use Test2::API qw{
test2_init_done
test2_stack
test2_set_is_end
test2_get_is_end
test2_ipc
test2_formatter_set
test2_formatter
};
my $init = test2_init_done();
my $stack = test2_stack();
my $ipc = test2_ipc();
test2_formatter_set($FORMATTER)
my $formatter = test2_formatter();
... And others ...
use Test2::API qw/context intercept run_subtest/;
This is the list of exports that are most commonly needed. If you are simply writing a tool, then this is probably all you need. If you need something and you cannot find it here, then you can also look at ``OTHER API EXPORTS''.
These exports lack the 'test2_' prefix because of how important/common they are. Exports in the ``OTHER API EXPORTS'' section have the 'test2_' prefix to ensure they stand out.
The "context()" function will always return the current context. If there is already a context active, it will be returned. If there is not an active context, one will be generated. When a context is generated it will default to using the file and line number where the currently running sub was called from.
Please see ``CRITICAL DETAILS'' in Test2::API::Context for important rules about what you can and cannot do with a context once it is obtained.
Note This function will throw an exception if you ignore the context object it returns.
Note On perls 5.14+ a depth check is used to insure there are no context leaks. This cannot be safely done on older perls due to <https://rt.perl.org/Public/Bug/Display.html?id=127774> You can forcefully enable it either by setting "$ENV{T2_CHECK_DEPTH} = 1" or "$Test2::API::DO_DEPTH_CHECK = 1" BEFORE loading Test2::API.
OPTIONAL PARAMETERS
All parameters to "context" are optional.
sub third_party_tool {
my $sub = shift;
... # Does not obtain a context
$sub->();
...
}
third_party_tool(sub {
my $ctx = context(level => 1);
...
$ctx->release;
});
sub my_context {
my %params = ( wrapped => 0, @_ );
$params{wrapped}++;
my $ctx = context(%params);
...
return $ctx;
}
sub my_tool {
my $ctx = my_context();
...
$ctx->release;
}
If you do not do this, then tools you call that also check for a context will notice that the context they grabbed was created at the same stack depth, which will trigger protective measures that warn you and destroy the existing context.
sub foo {
my $ctx = context(on_init => sub { 'will run' });
my $inner = sub {
# This callback is not run since we are getting the existing
# context from our parent sub.
my $ctx = context(on_init => sub { 'will NOT run' });
$ctx->release;
}
$inner->();
$ctx->release;
}
sub foo {
my $ctx = context(on_release => sub { 'will run second' });
my $inner = sub {
my $ctx = context(on_release => sub { 'will run first' });
# Neither callback runs on this release
$ctx->release;
}
$inner->();
# Both callbacks run here.
$ctx->release;
}
This is intended as a shortcut that lets you release your context and return a value in one statement. This function will get your context, and an optional return value. It will release your context, then return your value. Scalar context is always assumed.
sub tool {
my $ctx = context();
...
return release $ctx, 1;
}
This tool is most useful when you want to return the value you get from calling a function that needs to see the current context:
my $ctx = context();
my $out = some_tool(...);
$ctx->release;
return $out;
We can combine the last 3 lines of the above like so:
my $ctx = context();
release $ctx, some_tool(...);
sub my_tool {
context_do {
my $ctx = shift;
my (@args) = @_;
$ctx->ok(1, "pass");
...
# No need to call $ctx->release, done for you on scope exit.
} @_;
}
Using this inside your test tool takes care of a lot of boilerplate for you. It will ensure a context is acquired. It will capture and rethrow any exception. It will insure the context is released when you are done. It preserves the subroutine call context (array, scalar, void).
This is the safest way to write a test tool. The only two downsides to this are a slight performance decrease, and some extra indentation in your source. If the indentation is a problem for you then you can take a peek at the next section.
sub my_tool(&) {
my $code = shift;
my $ctx = context();
...
no_context {
# Things in here will not see our current context, they get a new
# one.
$code->();
};
...
$ctx->release;
};
This tool will hide a context for the provided block of code. This means any tools run inside the block will get a completely new context if they acquire one. The new context will be inherited by tools nested below the one that acquired it.
This will normally hide the current context for the top hub. If you need to hide the context for a different hub you can pass in the optional $hid parameter.
my $events = intercept {
ok(1, "pass");
ok(0, "fail");
...
};
This function takes a codeblock as its only argument, and it has a prototype. It will execute the codeblock, intercepting any generated events in the process. It will return an array reference with all the generated event objects. All events should be subclasses of Test2::Event.
This is a very low-level subtest tool. This is useful for writing tools which produce subtests. This is not intended for people simply writing tests.
run_subtest($NAME, \&CODE, $BUFFERED, @ARGS)
# or
run_subtest($NAME, \&CODE, \%PARAMS, @ARGS)
This will run the provided codeblock with the args in @args. This codeblock will be run as a subtest. A subtest is an isolated test state that is condensed into a single Test2::Event::Subtest event, which contains all events generated inside the subtest.
ARGUMENTS:
Keys that are removed and used by run_subtest:
Set this to true if your tool is producing subtests without user-specified subs.
BUFFERED VS UNBUFFERED (OR STREAMED)
Normally all events inside and outside a subtest are sent to the formatter immediately by the hub. Sometimes it is desirable to hold off sending events within a subtest until the subtest is complete. This usually depends on the formatter being used.
At the end of the subtest, the final Test2::Event::Subtest event is sent to the formatter.
A formatter can specify by implementing the "hide_buffered()" method. If this method returns true then events generated inside a buffered subtest will not be sent independently of the final subtest event.
An example of how this is used is the Test2::Formatter::TAP formatter. For unbuffered subtests the events are rendered as they are generated. At the end of the subtest, the final subtest event is rendered, but the "subevents" attribute is ignored. For buffered subtests the opposite occurs, the events are NOT rendered as they are generated, instead the "subevents" attribute is used to render them all at once. This is useful when running subtests tests in parallel, since without it the output from subtests would be interleaved together.
All exports are optional. You need to list which ones you want at import time:
use Test2::API qw/test2_init_done .../;
This is used to prevent the use of "caller()" in END blocks which can cause segfaults. This is only necessary in some persistent environments that may have multiple END phases.
Waiting is turned on by default. Waiting will cause the parent process/thread to wait until all child processes and threads are finished before exiting. You will almost never want to turn this off.
This can be used to get/set the no_wait status. Waiting is turned on by default. Waiting will cause the parent process/thread to wait until all child processes and threads are finished before exiting. You will almost never want to turn this off.
test2_add_callback_exit(
sub {
my ($context, $exit, \$new_exit) = @_;
...
}
);
The $context passed in will be an instance of Test2::API::Context. The $exit argument will be the original exit code before anything modified it. $$new_exit is a reference to the new exit code. You may modify this to change the exit code. Please note that $$new_exit may already be different from $exit
test2_add_callback_context_acquire(sub {
my $params = shift;
$params->{level}++;
});
This is a very scary API function. Please do not use this unless you need to. This is here for Test::Builder and backwards compatibility. This has you directly manipulate the hash instead of returning a new one for performance reasons.
The sub you provide should always return a unique identifier. Most things will expect a proper UUID string, however nothing in Test2::API enforces this.
The sub will receive exactly 1 argument, the type of thing being tagged 'context', 'hub', or 'event'. In the future additional things may be tagged, in which case new strings will be passed in. These are purely informative, you can (and usually should) ignore them.
Note: After calling this "test2_ipc_get_pending()" will return 1. This is intentional, and not avoidable.
This returns 0 if there are (most likely) no pending events.
This returns 1 if there are (likely) pending events. Upon return it will reset, nothing else will be able to see that there were pending events.
The default value is 30 seconds.
You can override this default using the "T2_FORMATTER" environment variable.
Normally 'Test2::Formatter::' is prefixed to the value in the environment variable:
$ T2_FORMATTER='TAP' perl test.t # Use the Test2::Formatter::TAP formatter
$ T2_FORMATTER='Foo' perl test.t # Use the Test2::Formatter::Foo formatter
If you want to specify a full module name you use the '+' prefix:
$ T2_FORMATTER='+Foo::Bar' perl test.t # Use the Foo::Bar formatter
Test2::IPC - The IPC system used for threading/fork support.
Test2::Formatter - Formatters such as TAP live here.
Test2::Event - Events live in this namespace.
Test2::Hub - All events eventually funnel through a hub. Custom hubs are how "intercept()" and "run_subtest()" are implemented.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://dev.perl.org/licenses/