MAN page from OpenSuSE perl-Perlito5-9.028-lp156.4.1.noarch.rpm

Perlito5X::Test2::API

Section: User Contributed Perl Documentation (3)
Updated: 2024-12-05
Index

NAME

Test2::API - Primary interface for writing Test2 based testing tools.

INTERNALS NOTE

The internals of this package are subject to change at any time! The publicmethods provided will not change in backwards-incompatible ways (once there isa stable release), but the underlying implementation details might.Do not break encapsulation here!

Currently the implementation is to create a single instance of theTest2::API::Instance Object. All class methods defer to the singleinstance. There is no public access to the singleton, and that is intentional.The class methods provided by this package provide the only functionalitypublicly exposed.

This is done primarily to avoid the problems Test::Builder had by exposing itssingleton. We do not want anyone to replace this singleton, rebless it, ordirectly muck with its internals. If you need to do something and cannotbecause of the restrictions placed here, then please report it as an issue. Ifpossible, we will create a way for you to implement your functionality withoutexposing things that should not be exposed.

DESCRIPTION

This package exports all the functions necessary to write and/or verify testingtools. Using these building blocks you can begin writing test tools veryquickly. You are also provided with tools that help you to test the tools youwrite.

SYNOPSIS

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 available on the context object.

TESTING YOUR TOOLS

The "intercept { ... }" tool lets you temporarily intercept all eventsgenerated 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_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 ...

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 simplywriting a tool, then this is probably all you need. If you need something andyou cannot find it here, then you can also look at ``OTHER API EXPORTS''.

These exports lack the 'test2_' prefix because of how important/common theyare. Exports in the ``OTHER API EXPORTS'' section have the 'test2_' prefix toensure they stand out.

context(...)

Usage:

$ctx = context()
$ctx = context(%params)

The "context()" function will always return the current context. Ifthere is already a context active, it will be returned. If there is not anactive context, one will be generated. When a context is generated it willdefault to using the file and line number where the currently running sub wascalled from.

Please see ``CRITICAL DETAILS'' in Test2::API::Context for important rules aboutwhat you can and cannot do with a context once it is obtained.

Note This function will throw an exception if you ignore the context objectit returns.

Note On perls 5.14+ a depth check is used to insure there are no contextleaks. 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.

level => $int

If you must obtain a context in a sub deeper than your entry point you can usethis to tell it how many EXTRA stack frames to look back. If this option is notprovided 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, then tools you call that also check for a context willnotice that the context they grabbed was created at the same stack depth, whichwill trigger protective measures that warn you and destroy the existingcontext.

stack => $stack

Normally "context()" looks at the global hub stack. If you are maintainingyour own Test2::API::Stack instance you may pass it in to be usedinstead of the global one.

hub => $hub

Use this parameter if you want to obtain the context for a specific hub insteadof 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 callto "context()" generated a new context. The callback WILL NOT be called if"context()" is returning an existing context. The only argument passed intothe 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 contextinstance is released. This callback will be added to the returned context evenif 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 avalue in one statement. This function will get your context, and an optionalreturn value. It will release your context, then return your value. Scalarcontext 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 callinga 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. Itwill ensure a context is acquired. It will capture and rethrow any exception. Itwill insure the context is released when you are done. It preserves thesubroutine call context (array, scalar, void).

This is the safest way to write a test tool. The only two downsides to this are aslight performance decrease, and some extra indentation in your source. If theindentation is a problem for you then you can take a peek at the next section.

no_context(&;$)

Usage:

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 anytools run inside the block will get a completely new context if they acquireone. The new context will be inherited by tools nested below the one thatacquired it.

This will normally hide the current context for the top hub. If you need tohide the context for a different hub you can pass in the optional $hidparameter.

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 theprocess. It will return an array reference with all the generated eventobjects. All events should be subclasses of Test2::Event.

This is a very low-level subtest tool. This is useful for writing tools whichproduce subtests. This is not intended for people simply writing tests.

run_subtest(...)

Usage:

    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 codeblockwill be run as a subtest. A subtest is an isolated test state that is condensedinto a single Test2::Event::Subtest event, which contains all eventsgenerated inside the subtest.

ARGUMENTS:

$NAME

The name of the subtest.

\&CODE

The code to run inside the subtest.

$BUFFERED or \%PARAMS

If this is a simple scalar then it will be treated as a boolean for the'buffered' setting. If this is a hash reference then it will be used as aparameters hash. The param hash will be used for hub construction (with thespecified keys removed).

Keys that are removed and used by run_subtest:

'buffered' => $bool: Toggle buffered status.
'inherit_trace' => $bool: Normally the subtest hub is pushed and the sub is allowed to generate its ownroot context for the hub. When this setting is turned on a root context will becreated for the hub that shares the same trace as the current context.
Set this to true if your tool is producing subtests without user-specifiedsubs.

@ARGS

Any extra arguments you want passed into the subtest code.

BUFFERED VS UNBUFFERED (OR STREAMED)

Normally all events inside and outside a subtest are sent to the formatterimmediately by the hub. Sometimes it is desirable to hold off sending eventswithin a subtest until the subtest is complete. This usually depends on theformatter being used.

Things not effected by this flag: In both cases events are generated and stored in an array. This array iseventually used to populate the "subevents" attribute on theTest2::Event::Subtest event that is generated at the end of the subtest.This flag has no effect on this part, it always happens.
At the end of the subtest, the final Test2::Event::Subtest event is sent tothe formatter.
Things that are effected by this flag: The "buffered" attribute of the Test2::Event::Subtest event will be set tothe value of this flag. This means any formatter, listener, etc which looks atthe event will know if it was buffered.
Things that are formatter dependant: Events within a buffered subtest may or may not be sent to the formatter asthey happen. If a formatter fails to specify then the default is to NOT SENDthe events as they are generated, instead the formatter can pull them from the"subevents" attribute.
A formatter can specify by implementing the "hide_buffered()" method. If thismethod returns true then events generated inside a buffered subtest will not besent independently of the final subtest event.

An example of how this is used is the Test2::Formatter::TAP formatter. Forunbuffered subtests the events are rendered as they are generated. At the endof the subtest, the final subtest event is rendered, but the "subevents"attribute is ignored. For buffered subtests the opposite occurs, the events areNOT rendered as they are generated, instead the "subevents" attribute is usedto render them all at once. This is useful when running subtests tests inparallel, since without it the output from subtests would be interleavedtogether.

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 APIEXPORTS'' section before looking here. This section is one where ``Great powercomes with great responsibility''. It is possible to break things badly if youare 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 beeninitialized. It will return false if they have not. Init happens as late aspossible. It happens as soon as a tool requests the IPC instance, theformatter, or the stack.
$bool = test2_load_done(): This will simply return the boolean value of the loaded flag. If Test2 hasfinished loading this will be true, otherwise false. Loading is consideredcomplete the first time a tool requests a context.
test2_set_is_end()
test2_set_is_end($bool): This is used to toggle Test2's belief that the END phase has already started.With no arguments this will set it to true. With arguments it will set it tothe first argument's value.
This is used to prevent the use of "caller()" in END blocks which can causesegfaults. This is only necessary in some persistent environments that may havemultiple END phases.
$bool = test2_get_is_end(): Check if Test2 believes it is the END phase.
$stack = test2_stack(): This will return the global Test2::API::Stack instance. If this has notyet 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 bydefault. Waiting will cause the parent process/thread to wait until all childprocesses and threads are finished before exiting. You will almost never wantto turn this off.

BEHAVIOR HOOKS

These are hooks that allow you to add custom behavior to actions taken by Test2and 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. Thisis too late to add additional results, the main use of this callback is to set theexit 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 tochange the exit code. Please note that $$new_exit may already be differentfrom $exit

test2_add_callback_post_load(sub { ... })

Add a callback that will be called when Test2 is finished loading. Thismeans 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 immediately.

test2_add_callback_context_acquire(sub { ... })

Add a callback that will be called every time someone tries to acquire acontext. This will be called on EVERY call to "context()". It gets a singleargument, a reference to the hash of parameters being used the construct thecontext. This is your chance to change the parameters by directly altering thehash.

    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 youdirectly manipulate the hash instead of returning a new one for performancereasons.

test2_add_callback_context_init(sub { ... })

Add a callback that will be called every time a new context is created. Thecallback 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. Thecallback 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 yetbeen 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 thelist.

@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 everytime 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 onthemselves.

test2_ipc_set_pending($uniq_val)

Tell other processes and events that an event is pending. $uniq_val shouldbe a unique value no other thread/process will generate.

Note: After calling this "test2_ipc_get_pending()" will return 1. This isintentional, 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. Bydefault 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 theenvironment 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 willoverride 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. Ifthis is called after initialization a warning will be issued.

OTHER EXAMPLES

See the "/Examples/" directory included in this distribution.

MAGIC

This package has an END block. This END block is responsible for setting theexit code based on the test results. This end block also calls the callbacks thatcan be added to this package.