Test2::API(3perl)

💖 NAME 💖

Test2::API — the absolute main-character primary interface for writing Test2-based testing tools. Yep, this is the Test2::API(3perl) page, from the Perl Programmers Reference Guide, and it is foundational bestie. 💅

---

🚨 INTERNALS NOTE 🚨

okay so real talk — the internals of this package are subject to change at any time. fr fr.

The public methods provided will not change in backwards-incompatible ways (once there is a stable release), but the underlying implementation details? those might. So pls, do not break encapsulation here, I am begging. 🙈

Currently the implementation is to create a single instance of the Test2::API::Instance Object. All class methods defer to that single instance. There is no public access to the singleton, and that is super intentional. The class methods this package provides are the only functionality publicly exposed.

Why tho? Because it avoids 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 you can't 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 test the tools you write. it's giving tooling for your tooling, and honestly? iconic. ✨

---

🦋 SYNOPSIS 🦋

✍️ WRITING A TOOL

The context() method is your primary interface into the Test2 framework. Your whole personality for the next five minutes, lowkey.

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 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");
};

As of version 1.302178 this now returns an arrayref that is also an instance of Test2::API::InterceptResult. See the Test2::API::InterceptResult documentation for details on how to best use it. bestie, that's a glow-up.

🧰 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
    test2_is_testing_done
};

my $init  = test2_init_done();
my $stack = test2_stack();
my $ipc   = test2_ipc();

test2_formatter_set($FORMATTER)
my $formatter = test2_formatter();

... And others ...

---

🌈 ENVIRONMENT VARIABLES 🌈

See Test2::Env for a list of meaningful environment variables. yes, they got their own whole page. main character energy. 💜

---

👑 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. 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. read it, I'm not playing. 😭

Note — This function will throw an exception if you ignore the context object it returns. 💀 do not ghost the context.

Note — On perls 5.14+ a depth check is used to ensure 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. every single one. no pressure. 🌸

level => $int

If you must obtain a context in a sub deeper 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, 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. so like, do it. 🙏

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 — obsessed with the efficiency tbh:

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 ensure the context is released when you are done. It preserves the subroutine call context (list, 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. 👀

🍓 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 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");
    ...
};

Okay so bestie, run that codeblock it takes as its only argument — yep, it has a prototype, very demure — and it will intercept every single event generated in the process 😌. What you get back is an array reference holding all those generated event objects. And heads up: every one of those events should be a subclass of Test2::Event.

As of version 1.302178, the events array you get back is blessed as a Test2::API::InterceptResult instance 💅. Test2::API::InterceptResult hands you a genuinely helpful interface for filtering and/or inspecting the events list as a whole, or poking at individual events inside that list. It's giving organized ✨.

This whole thing is intended to help you test your test code, bestie 🧪. It is not intended for people who are simply writing tests. Different job, different girlie 🎀.

---

🌸 run_subtest(...) 🌸

Usage, copy it exactly bestie:

run_subtest($NAME, \&CODE, $BUFFERED, @ARGS)

# or

run_subtest($NAME, \&CODE, \%PARAMS, @ARGS)

So the tea ☕: this runs the codeblock you hand it, with the args in @args. That codeblock gets run as a subtest. A subtest is an isolated test state that gets condensed down into a single Test2::Event::Subtest event 💫, and that one event contains all the events generated inside the subtest. Condensed. Iconic. Chef's kiss.

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 gets treated as a boolean for the 'buffered' setting ✨. If it's a hash reference instead, then it's used as a parameters hash. That param hash is used for hub construction, with the specified keys removed 👀.

Keys that are removed and used by run_subtest:

• 'buffered' => $bool — toggles buffered status 🔁.
• 'inherit_trace' => $bool — normally the subtest hub is pushed and the sub is allowed to generate its own root context for the hub. When this setting is turned on, a root context will be created for the hub that shares the same trace as the current context 🧬. Set this to true if your tool is producing subtests without user-specified subs 💅.
• 'no_fork' => $bool — defaults to off. Normally forking inside a subtest will actually fork the subtest, resulting in 2 final subtest events. This parameter turns off that behavior, so only the original process/thread will return a final subtest event 👑.

• @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 formatter immediately by the hub, no waiting, no chill 😤. But sometimes it's desirable to hold off sending events within a subtest until the subtest is complete. Whether you want that usually depends on which formatter you're using 🤔.

Things not affected by this flag

In both cases events are generated and stored in an array 💾. That array is eventually used to populate the "subevents" attribute on the Test2::Event::Subtest event generated at the end of the subtest. This flag has no effect on this part — it always happens, no cap 🧚.

At the end of the subtest, the final Test2::Event::Subtest event is sent to the formatter ✉️.

Things that are affected by this flag

The "buffered" attribute of the Test2::Event::Subtest event will be set to the value of this flag 🚩. Which means any formatter, listener, etc. that looks at the event will know whether it was buffered. Transparency, we love to see it ✨.

Things that are formatter dependent

Events within a buffered subtest may or may not be sent to the formatter as they happen 🫠. If a formatter fails to specify, then the default is to NOT SEND the 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 that 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, and instead the "subevents" attribute is used to render them all at once. This is super useful when running subtests tests in parallel 🏃‍♀️🏃‍♀️, since without it the output from subtests would be interleaved together and that's a mess, bestie.

---

💖 OTHER API EXPORTS 💖

Okay so, the exports in this section are not commonly needed. They all have the 'test2_' prefix to help ensure they stand out 🌟. You should look at the "MAIN API EXPORTS" section before you look here, fr fr. This section is one where "Great power comes with great responsibility" 🕷️. It is possible to break things badly if you are not careful with these. No cap.

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 returns true if the stack and IPC instances have already been initialized ✅. It returns 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 simply returns 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.
• 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 sets it to true. With arguments it sets it to the first argument's value.

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.

• $bool = test2_get_is_end() — check if Test2 believes it is the END phase 🤔.
• $stack = test2_stack() — this returns the global Test2::API::Stack instance 📚. If this has not yet been initialized it will be initialized now, boom, main character energy.
• $bool = test2_is_testing_done() — this returns true if testing is complete and no other events should be sent 🛑. This is useful in things like warning handlers, where you might want to turn warnings into events, but need them to start acting like normal warnings when testing is done:

$SIG{__WARN__} = sub {
    my ($warning) = @_;

    if (test2_is_testing_done()) {
        warn @_;
    }
    else {
        my $ctx = context();
        ...
        $ctx->release
    }
}

• test2_ipc_disable — disable IPC 🚫.
• $bool = test2_ipc_disabled — check if IPC is disabled 👀.
• test2_ipc_wait_enable() test2_ipc_wait_disable() $bool = test2_ipc_wait_enabled() — these turn IPC waiting on and off, or check the current value of the flag 🔁.

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, bestie, seriously 😭.

• $bool = test2_no_wait() test2_no_wait($bool) — DISCOURAGED 🚨: this is a confusing interface, it is better to use test2_ipc_wait_enable(), test2_ipc_wait_disable() and test2_ipc_wait_enabled() 💅.

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 😤.

• $fh = test2_stdout() $fh = test2_stderr() — these functions return the filehandles that test output should be written to 📝. They are primarily useful when writing a custom formatter and code that turns events into actual output (TAP, etc.). They will return a dupe of the original filehandles, that formatted output can be sent to regardless of whatever state the currently running test may have left STDOUT and STDERR in 🫶. Iconic safety feature.
• test2_reset_io() — re-dupe the internal filehandles returned by test2_stdout() and test2_stderr() from the current STDOUT and STDERR 🔄. You shouldn't need to do this except in very peculiar situations (for example, you're testing a new formatter and you need control over where the formatter is sending its output 👀).

---

🎀 BEHAVIOR HOOKS 🎀

These are hooks that let you add custom behavior to actions taken by Test2 and tools built on top of it ✨.

• test2_add_callback_exit(sub { ... }) — this adds 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 immediately ⚡.
• test2_add_callback_testing_done(sub { ... }) — this adds your coderef as a follow-up to the root hub after Test2 is finished loading 🌱.

This is essentially a helper to do the following:

test2_add_callback_post_load(sub {
    my $stack = test2_stack();
    $stack->top; # Ensure we have a hub
    my ($hub) = Test2::API::test2_stack->all;

    $hub->set_active(1);

    $hub->follow_up(sub { ... }); # <-- Your coderef here
});

• 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 to the hash of parameters being used to 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}++;
});

okay so this next one is a very scary API function fr fr 😭 — pls do not use it unless you genuinely have to. it exists for Test::Builder and for backwards compatibility, that's it. and the way it works? it has you directly manipulate the hash instead of returning a shiny new one, which is purely for performance reasons. scary. 💀

• test2_add_callback_context_init(sub { ... }) — drops in a callback that gets called every single time a new context is created 🎀 the callback receives the freshly created context as its one and only argument.
• test2_add_callback_context_release(sub { ... }) — same energy, different moment: this callback fires every time a context is released. it gets the released context as its only argument. ✨
• test2_add_callback_pre_subtest(sub { ... }) — this one runs every time a subtest is about to be run 🏃♀️ the callback gets the subtest name, the coderef, and any arguments. slay.
• @list = test2_list_context_acquire_callbacks() — hands you back 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.
• @list = test2_list_pre_subtest_callbacks() — returns all the pre-subtest callback references.
• test2_add_uuid_via(sub { ... })
• $sub = test2_add_uuid_via() — this is where you get to plug in your very own UUID generator 🔥 if you provide one, UUIDs get attached to all events, hubs, and contexts. super useful for storing, tracking, and linking all those objects together, iykyk.

the sub you hand over should always return a unique identifier. most things out there will expect a proper UUID string, but ngl nothing in Test2::API actually enforces that.

your sub will receive exactly 1 argument: the type of thing being tagged, which is 'context', 'hub', or 'event'. in the future more things might get tagged, in which case brand new strings will get passed in. these are purely informative — you can (and usually should) just ignore them. 🙈

• test2_add_pending_diag($diag)
• test2_add_pending_diag($diag1, $diag2) — queues up a diagnostics message that will be issued the next time a context in which a failure occurred gets released 🌸

think of it like this: "if the next bit causes a failed assertion, add this diagnostics message." periodt.

• @diags = test2_get_pending_diags() — grab all the current pending diagnostics messages.
• @diags = test2_clear_pending_diags() — clear any pending diagnostics, and return them to you on the way out. 🫶

---

🦋 IPC AND CONCURRENCY 🦋

these bad boys let you access, or specify, the IPC system internals. the plumbing, bestie. 🚰

• $bool = test2_has_ipc() — check whether IPC is enabled.
• $ipc = test2_ipc() — returns the global Test2::IPC::Driver instance. if it hasn't been initialized yet, well, it gets initialized right now, bestie. ✨
• test2_ipc_add_driver($DRIVER) — add an IPC driver to the list. heads up: this adds 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 culls events from other processes and threads every single time a context is created 👑
• test2_ipc_disable_polling() — turn off IPC polling. bye 💅
• test2_ipc_enable_shm() — legacy alert 🚨 this is currently a no-op that returns 0; like, it just does that.
• test2_ipc_set_pending($uniq_val) — tells other processes and events that an event is pending. $uniq_val should be a unique value that no other thread/process will ever generate. no cap.

Note: after calling this, test2_ipc_get_pending() will return 1. this is intentional, and not avoidable. so don't come for me 😭

• $pending = test2_ipc_get_pending() — the vibe check returns:
  • -1 if there is no way to check (so, assume yes)
  • 0 if there are (most likely) no pending events
  • 1 if there are (likely) pending events — and upon return it will reset, so nothing else will be able to see that there were pending events. one-time tea ☕
• $timeout = test2_ipc_get_timeout()
• test2_ipc_set_timeout($timeout) — get/set the timeout value for the IPC system. this timeout is how long the IPC system will wait for child processes and threads to finish before it aborts. the default value is 30 seconds. ⏰

---

🎀 MANAGING FORMATTERS 🎀

these let you access, or specify, the formatters that can/should be used. glow-up time for your output ✨

• $formatter = test2_formatter — returns the global formatter class. not an instance, bestie, the class. by default the formatter is set to Test2::Formatter::TAP.

you can override that default with the "T2_FORMATTER" environment variable. 💜

normally 'Test2::Formatter::' gets prefixed onto whatever value is 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

and if you wanna 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. and listen: this can only be set once 👀 also note it will override anything specified in the 'T2_FORMATTER' environment variable. it said main character energy, sorry.
• @formatters = test2_formatters() — get a list of all loaded formatters.
• test2_formatter_add($class_or_instance) — add a formatter to the list. the last formatter added is the one used at initialization. but if you call this after initialization, a warning will be issued. ⚠️

---

⏱️ TIME STAMPS ⏱️

you can enable or disable timestamps in trace facets 🕰️ they're disabled by default, for compatibility and performance reasons.

• test2_enable_trace_stamps() — enable stamps in traces.
• test2_disable_trace_stamps() — disable stamps in traces.
• $bool = test2_trace_stamps_enabled() — check the status of trace stamps.

---

🌈 OTHER EXAMPLES 🌈

see the "/Examples/" directory included in this distribution. it's giving tutorial, go look 🍓

---

👀 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. iconic behaviour tbh.

---

🔮 MAGIC 🔮

this package has an END block 🪄 and this END block is responsible for setting the exit code based on the test results. it also calls the callbacks that can be added to this package. so yeah. magic. don't question it ✨

---

💾 SOURCE 💾

the source code repository for Test2 can be found at <https://github.com/Test-More/test-more/>. go star it bestie ⭐

---

🫶 MAINTAINERS 🫶

Chad Granum <exodist@cpan.org>

---

💖 AUTHORS 💖

Chad Granum <exodist@cpan.org>

---

📜 COPYRIGHT 📜

Copyright Chad Granum <exodist@cpan.org>.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

see <https://dev.perl.org/licenses/>

---

and that's the whole page, bestie, we made it 🎉 this was Test2::API(3perl), shipped with perl v5.44.0 and dated 2026-10-17. go forth and test slayfully 💅✨🌸