Provided by: libtest2-perl_0.000025-1_all 
NAME
Test2::API - Primary interface for writing Test2 based testing tools.
EXPERIMENTAL RELEASE
This is an experimental release. Using this right now is not recommended.
***INTERNALS NOTE***
The internals of this package are subject to change at any time! The public methods provided will not
change in backwords incompatible ways (once there is a stable release), but the underlying implementation
details might. Do not break encapsulation here!
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.
DESCRIPTION
This package exports all the functions necessary to write and/or verify testing tools. Using these
building blocks you can begin writing test tools very quickly. You are also provided with tools that help
you to test the tools you write.
SYNOPSYS
WRITING A TOOL
The "context()" method is your primary interface into the Test2 framework.
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 avabilable on the context object.
TESTING YOUR TOOLS
The "intercept { ... }" tool lets you temporarily intercept all events generated by the test system:
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");
OTHER API FUNCTIONS
use Test2::API qw{
test2_init_done
test2_stack
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 ...
MAIN API EXPORTS
All exports are optional, you must specify subs to import.
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.
context(...)
Usage:
$ctx = context()
$ctx = context(%params)
The "context()" function will always return the current context to you. 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.
OPTIONAL PARAMETERS
All parameters to "context" are optional.
level => $int
If you must obtain a context in a sub deper than your entry point you can use this to tell it how
many EXTRA stack frames to look back. If this option is not provided the default of 0 is used.
sub third_party_tool {
my $sub = shift;
... # Does not obtain a context
$sub->();
...
}
third_party_tool(sub {
my $ctx = context(level => 1);
...
$ctx->release;
});
wrapped => $int
Use this if you need to write your own tool that wraps a call to "context()" with the intent that it
should return a context object.
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 than 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.
stack => $stack
Normally "context()" looks at the global hub stack. If you are maintaining your own Test2::API::Stack
instance you may pass it in to be used instead of the global one.
hub => $hub
Use this parameter if you want to obtain the context for a specific hub instead of whatever one
happens to be at the top of the stack.
on_init => sub { ... }
This lets you provide a callback sub that will be called ONLY if your call to "context()" generated a
new context. The callback WILL NOT be called if "context()" is returning an existing context. The
only argument passed into the callback will be the context object itself.
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;
}
on_release => sub { ... }
This lets you provide a callback sub that will be called when the context instance is released. This
callback will be added to the returned context even if an existing context is returned. If multiple
calls to context add callbacks then all will be called in reverse order when the context is finally
released.
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;
}
release($;$)
Usage:
release $ctx;
release $ctx, ...;
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(...);
context_do(&;@)
Usage:
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 2 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.
no_context(&;$)
Useage:
no_context { ... };
no_context { ... } $hid;
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.
intercept(&)
Usage:
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(...)
Usage:
run_subtest($NAME, \&CODE, $BUFFERED, @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:
$NAME
The name of the subtest.
\&CODE
The code to run inside the subtest.
$BUFFERED
If this is true then the subtest will be buffered. In a buffered subtest the child events are hidden
from the formatter, the formatter will only receive the final <Test2:Event::Subtest> event. In an
unbuffered subtest the formatter will see all events as they happen, as well as the final one.
@ARGS
Any extra arguments you want passed into the subtest code.
OTHER API EXPORTS
Exports in this section are not commonly needed. These all have the 'test2_' prefix to help ensure they
stand out. You should look at the "MAIN API EXPORTS" section before looking here. This section is one
where "Great power comes with great responsiblity". It is possible to break things badly if you are not
careful with these.
All exports are optional, you need to list which ones you want at import time:
use Test2::API qw/test2_init_done .../;
STATUS AND INITIALIZATION STATE
These provide access to internal state and object instances.
$bool = test2_init_done()
This will return true if the stack and ipc instances have already been initialized. It will return
false if they have not. Init happens as late as possible, it happens as soon as a tool requests the
ipc instance, the formatter, or the stack.
$bool = test2_load_done()
This will simply return the boolean value of the loaded flag. If Test2 has finished loading this will
be true, otherwise false. Loading is considered complete the first time a tool requests a context.
$stack = test2_stack()
This will return the global Test2::API::Stack instance. If this has not yet been initialized it will
be initialized now.
$bool = test2_no_wait()
test2_no_wait($bool)
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.
BEHAVIOR HOOKS
These are hooks that allow you to add custom behavior to actions taken by Test2 and tools built on top of
it.
test2_add_callback_exit(sub { ... })
This can be used to add a callback that is called after all testing is done. This is too late to add
additional results, the main use of this callback is to set the exit code.
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_post_load(sub { ... })
Add a callback that will be called when Test2 is finished loading. This means the callback will be
run once, the first time a context is obtained. If Test2 has already finished loading then the
callback will be run immedietly.
test2_add_callback_context_acquire(sub { ... })
Add a callback that will be called every time someone tries to acquire a context. This will be called
on EVERY call to "context()". It gets a single argument, a reference the the hash of parameters being
used the construct the context. This is your chance to change the parameters by directly altering the
hash.
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.
test2_add_callback_context_init(sub { ... })
Add a callback that will be called every time a new context is created. The callback will receive the
newly created context as its only argument.
test2_add_callback_context_release(sub { ... })
Add a callback that will be called every time a context is released. The callback will receive the
released context as its only argument.
@list = test2_list_context_acquire_callbacks()
Return all the context acquire callback references.
@list = test2_list_context_init_callbacks()
Returns all the context init callback references.
@list = test2_list_context_release_callbacks()
Returns all the context release callback references.
@list = test2_list_exit_callbacks()
Returns all the exit callback references.
@list = test2_list_post_load_callbacks()
Returns all the post load callback references.
IPC AND CONCURRENCY
These let you access, or specify, the IPC system internals.
$ipc = test2_ipc()
This will return the global Test2::IPC::Driver instance. If this has not yet been initialized it will
be initialized now.
test2_ipc_add_driver($DRIVER)
Add an IPC driver to the list. This will add the driver to the start of the list.
@drivers = test2_ipc_drivers()
Get the list of IPC drivers.
$bool = test2_ipc_polling()
Check if polling is enabled.
test2_ipc_enable_polling()
Turn on polling. This will cull events from other processes and threads every time a context is
created.
test2_ipc_disable_polling()
Turn off IPC polling.
test2_ipc_enable_shm()
Turn on IPC shm. Only some IPC drivers use this, and most will turn it on themselves.
test2_ipc_set_pending($uniq_val)
Tell other processes and events that an event is pending. $uniq_val should be a unique value no other
thread/process will generate.
Note: After calling this "test2_ipc_get_pending()" will return 1. This is intentional, and not
avoidable.
$pending = test2_ipc_get_pending()
This returns -1 if there is no way to check (assume yes)
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.
MANAGING FORMATTERS
These let you access, or specify, the formatters that can/should be used.
$formatter = test2_formatter
This will return the global formatter class. This is not an instance. By default the formatter is set
to Test2::Formatter::TAP.
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_formatter_set($class_or_instance)
Set the global formatter class. This can only be set once. Note: This will override anything
specified in the 'T2_FORMATTER' environment variable.
@formatters = test2_formatters()
Get a list of all loaded formatters.
test2_formatter_add($class_or_instance)
Add a formatter to the list. Last formatter added is used at initialization. If this is called after
initialization a warning will be issued.
OTHER EXAMPLES
See the "/Examples/" directory included in this distribution.
SEE ALSO
Test2::API::Context - Detailed documentation of the context object.
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.
MAGIC
This package has an END block. This END block is responsible for setting the exit code based on the test
results. This end block also calls the callbacks that can be added to this package.
SOURCE
The source code repository for Test2 can be found at http://github.com/Test-More/Test2/.
MAINTAINERS
Chad Granum <exodist@cpan.org>
AUTHORS
Chad Granum <exodist@cpan.org>
COPYRIGHT
Copyright 2015 Chad Granum <exodist7@gmail.com>.
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/
perl v5.22.1 2016-02-06 Test2::API(3pm)