# perldoc > Test2::API

---
type: CommandReference
command: Test2::API
mode: perldoc
section: 
source: perldoc
---

## Quick Reference
- `context()` — Get the current context (or create one)
- `release($ctx, $return)` — Release context and return a value
- `context_do(&;@)` — Safe wrapper for acquiring/releasing context
- `no_context(&;$)` — Hide current context for a block of code
- `intercept(&)` — Capture all events generated within a block
- `run_subtest($name, \&code, $buffered|%params, @args)` — Run code as a subtest
- `test2_init_done()` — Check if Test2 is initialized
- `test2_stack()` — Get the global hub stack

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

## Synopsis
perl
use Test2::API qw/context release context_do no_context intercept run_subtest/;

# Writing a test tool
sub my_ok($;$) {
    my ($bool, $name) = @_;
    my $ctx = context();
    $ctx->ok($bool, $name);
    $ctx->release;
    return $bool;
}

# Testing your tools
use Test2::API qw/intercept/;
my $events = intercept {
    ok(1, "pass");
    ok(0, "fail");
};

# Other API functions
use Test2::API qw/test2_init_done test2_stack test2_ipc test2_formatter_set test2_formatter/;
## Options
### MAIN API EXPORTS
- `context()` — Return the current context (creates one if needed). Optional parameters: `level => $int`, `wrapped => $int`, `stack => $stack`, `hub => $hub`, `on_init => sub { ... }`, `on_release => sub { ... }`.
- `release($ctx, $return)` — Release the context and return `$return` (scalar context).
- `context_do(&;@)` — Acquire context, run the code block, release on scope exit. Passes `@_` to the block. Preserves call context.
- `no_context(&; $hid)` — Hide the current context for the code block. Optionally specify a hub ID.
- `intercept(&)` — Execute code block, intercept all generated events, return arrayref of `Test2::Event` objects. As of 1.302178, the arrayref is also a `Test2::API::InterceptResult` instance.
- `run_subtest($NAME, \&CODE, $BUFFERED|\%PARAMS, @ARGS)` — Run code as a subtest. Parameters: `buffered => $bool`, `inherit_trace => $bool`, `no_fork => $bool`. Events are condensed into a single `Test2::Event::Subtest` event.

### OTHER API EXPORTS
- `test2_init_done()` — Returns true if the stack and IPC have been initialized.
- `test2_load_done()` — Returns true if Test2 has finished loading.
- `test2_set_is_end($bool)` — Set the "is end" flag (default true if no arg).
- `test2_get_is_end()` — Check if Test2 believes it is in the END phase.
- `test2_stack()` — Returns the global `Test2::API::Stack` instance.
- `test2_is_testing_done()` — Returns true if testing is complete.
- `test2_ipc_disable()` — Disable IPC.
- `test2_ipc_disabled()` — Check if IPC is disabled.
- `test2_ipc_wait_enable()` — Enable waiting for child processes/threads.
- `test2_ipc_wait_disable()` — Disable waiting.
- `test2_ipc_wait_enabled()` — Check if waiting is enabled.
- `test2_no_wait($bool)` — Get/set no_wait status (discouraged; use above methods).
- `test2_stdout()` — Returns a dupe of the original STDOUT.
- `test2_stderr()` — Returns a dupe of the original STDERR.
- `test2_reset_io()` — Re-dupe internal filehandles from current STDOUT/STDERR.
- `test2_add_callback_exit(sub { ($ctx, $exit, \$new_exit) })` — Add callback for exit code setting.
- `test2_add_callback_post_load(sub { ... })` — Add callback called when Test2 finishes loading.
- `test2_add_callback_testing_done(sub { ... })` — Add callback as follow-up to root hub after loading.
- `test2_add_callback_context_acquire(sub { $params })` — Add callback called on every context acquisition.
- `test2_add_callback_context_init(sub { $ctx })` — Add callback called on new context creation.
- `test2_add_callback_context_release(sub { $ctx })` — Add callback called on context release.
- `test2_add_callback_pre_subtest(sub { $name, $code, @args })` — Add callback called before each subtest.
- `test2_list_context_acquire_callbacks()` — Returns list of context acquire callbacks.
- `test2_list_context_init_callbacks()` — Returns list of context init callbacks.
- `test2_list_context_release_callbacks()` — Returns list of context release callbacks.
- `test2_list_exit_callbacks()` — Returns list of exit callbacks.
- `test2_list_post_load_callbacks()` — Returns list of post load callbacks.
- `test2_list_pre_subtest_callbacks()` — Returns list of pre-subtest callbacks.
- `test2_add_uuid_via($sub)` — Set a UUID generator; `$sub` receives type ('context', 'hub', 'event').
- `test2_has_ipc()` — Check if IPC is enabled.
- `test2_ipc()` — Return the global IPC driver instance.
- `test2_ipc_add_driver($driver)` — Add an IPC driver to the start of the list.
- `test2_ipc_drivers()` — Get list of IPC drivers.
- `test2_ipc_polling()` — Check if polling is enabled.
- `test2_ipc_enable_polling()` — Enable polling (cull events on context creation).
- `test2_ipc_disable_polling()` — Disable polling.
- `test2_ipc_enable_shm()` — Legacy no-op, returns 0.
- `test2_ipc_set_pending($uniq_val)` — Signal pending event to other processes/threads.
- `test2_ipc_get_pending()` — Returns -1 (can't check), 0 (none), or 1 (pending; resets).
- `test2_ipc_get_timeout()` — Get the IPC timeout (default 30 seconds).
- `test2_ipc_set_timeout($timeout)` — Set the IPC timeout.
- `test2_formatter()` — Return the global formatter class (default `Test2::Formatter::TAP`; overridable via `T2_FORMATTER` env var).
- `test2_formatter_set($class)` — Set the global formatter class (once only).
- `test2_formatters()` — List all loaded formatters.
- `test2_formatter_add($class)` — Add a formatter to the list.

## Examples
perl
# Context acquisition and release
my $ctx = context();
$ctx->ok($bool, $name);
$ctx->release;

# Using release() to return a value
return release $ctx, $result;

# context_do() for safe tool writing
sub my_tool {
    context_do {
        my $ctx = shift;
        my (@args) = @_;
        $ctx->ok(1, "pass");
        # released automatically on scope exit
    } @_;
}

# Intercepting events
my $events = intercept {
    my_ok(1, "pass");
    my_ok(0, "fail");
};
# $events is an arrayref of Test2::Event objects

# Subtest with buffering
run_subtest("subtest name", \&code, 1, @args);
## See Also
- [Test2::API::Context](https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AAPI%3A%3AContext/markdown) - Detailed documentation of the context object.
- [Test2::IPC](https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AIPC/markdown) - The IPC system used for threading/fork support.
- [Test2::Formatter](https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AFormatter/markdown) - Formatters such as TAP.
- [Test2::Event](https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AEvent/markdown) - Events live in this namespace.
- [Test2::Hub](https://www.chedong.com/phpMan.php/perldoc/Test2%3A%3AHub/markdown) - All events funnel through a hub.