/ 
Test2-0.000011
/ Test2::Global

NAME

Test2::Global - Primary Synchronization point, this is where global stuff lives.

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::Global::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

There is a need to synchronize some details for all tests that run. This package stores these global objects. As little as possible is kept here, when possible things should not be global.

SYNOPSIS

use Test2::Global 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 ...

EXPORTS

All exports are optional, you must specify ones you want.

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::Context::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::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_init(sub { ... })

Add a callback that will be called every time a new context is created. The callback will recieve 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 recieve the released context as its only argument.

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.

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.

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/