Test2:...stance(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 Test2:...stance — manual page 3perl 💖

okay so bestie, we're reading Test2:...stance out of the Perl Programmers Reference Guide, and honestly? the title has literal dots in it, we love a mysterious icon ✨ don't worry about it, let's go 🦋

🎀 NAME 🎀

Test2::API::Instance — bestie... it's the Object used by Test2::API under the hood 💅

🫶 DESCRIPTION 🫶

okay so picture this: there's this ✨object✨ and its whole job is to hold all the global shared state that Test2 keeps track of. A single global instance of this package gets stored — and ngl, kind of obscured — by the Test2::API package. it's giving ✨ backstage crew energy ✨, you never see them, the show doesn't happen without them 🎭

and here's the thing bestie, listen: there is no reason to directly use this package. None. Zero. Zip 🙈 It's documented purely for completeness, that's it. This package can change, or go away completely at any time. Directly using it, or monkeypatching it, is not supported in any way shape or form.

🚨 fr fr, do not touch. Not "be careful" — not supported. not even a little. 🚨

✨ SYNOPSIS ✨

the whole opening number, verbatim:

use Test2::API::Instance;

my $obj = Test2::API::Instance->new;

and now... the method menu 🍓 every single one, no skips, no crumbs left behind:

  • $pid = $obj->pid — the PID of this instance 🫀
  • $obj->tid — the Thread ID of this instance 🧵
  • $obj->reset() — resets the object back to defaults, factory settings, clean slate 💫
  • $obj->load() — sets the internal state to loaded, and runs & stores the post-load callbacks ✔️
  • $bool = $obj->loaded — checks whether the state is set to loaded 🔍
  • $arrayref = $obj->post_load_callbacks — gets the post-load callbacks 📋
  • $obj->add_post_load_callback(sub { ... }) — adds a post-load callback. If load() has already been called, the callback gets executed immediately. If load() hasn't been called yet, the callback gets stored and executed later, when load() is called 🔮
  • $hashref = $obj->contexts() — gets a hashref of all the active contexts, keyed by hub id 🗂️
  • $arrayref = $obj->context_acquire_callbacks — gets all the context acquire callbacks 🫴
  • $arrayref = $obj->context_init_callbacks — gets all the context init callbacks 🌱
  • $arrayref = $obj->context_release_callbacks — gets all the context release callbacks 🕊️
  • $arrayref = $obj->pre_subtest_callbacks — gets all the pre-subtest callbacks 🎬
  • $obj->add_context_init_callback(sub { ... }) — adds a context init callback. The subs get called every single time a context is created, and they receive the newly created context as their only argument 🍼
  • $obj->add_context_release_callback(sub { ... }) — adds a context release callback. The subs get called every time a context is released, and they receive the released context as their only argument. 🫧 these callbacks should not call release on the context — no, bestie, don't do it 🙅‍♀️
  • $obj->add_pre_subtest_callback(sub { ... }) — adds a pre-subtest callback. The subs get called every time a subtest is going to be run, and they receive the subtest name, the coderef, and any arguments 🏃‍♀️
  • $obj->set_exit() — this one is intended to be called in an "END { ... }" block. It looks at the test state and sets $?. It also calls any end callbacks, and waits on child processes/threads 👋
  • $obj->set_ipc_pending($val) — tells other processes and threads that there's a pending event. $val should be a unique value that no other thread/process will generate 🔔
📌 Note: this will also make the current process see a pending event.
  • $pending = $obj->get_ipc_pending() — here's the readout, three possible answers:
    • returns -1 if it's not possible to know 🤷‍♀️
    • returns 0 if there are no pending events 🚫
    • returns 1 if there are pending events 🚨
  • $timeout = $obj->ipc_timeout; and $obj->set_ipc_timeout($timeout); — how long to wait for child processes and threads before aborting ⏳
  • $drivers = $obj->ipc_drivers — gets the list of IPC drivers 🚗
  • $obj->add_ipc_driver($DRIVER_CLASS) — adds an IPC driver to the list. The most recently added IPC driver becomes the global one during initialization. If a driver is added after initialization has already occurred, a warning gets generated 😬:
"IPC driver $driver loaded too late to be used as the global ipc driver"
  • $bool = $obj->ipc_polling — checks whether polling is enabled 👀
  • $obj->enable_ipc_polling — turns polling on. This culls events from other processes and threads every time a context is created 🧹
  • $obj->disable_ipc_polling — turns IPC polling off 🌙
  • $bool = $obj->no_wait and $bool = $obj->set_no_wait($bool) — get/set no_wait. This option is used to turn off process/thread waiting at exit 🛑
  • $arrayref = $obj->exit_callbacks — gets the exit callbacks 🚪
  • $obj->add_exit_callback(sub { ... }) — adds an exit callback. This callback gets called by set_exit() 📞
  • $bool = $obj->finalized — checks whether the object is finalized. Finalization happens when either ipc(), stack(), or format() are called on the object. Once finalization happens, these fields are considered unchangeable — and bestie, that's not enforced here, it's enforced by Test2 ⚠️
  • $ipc = $obj->ipc — gets the one true IPC instance 👑
  • $obj->ipc_disable — turns IPC off 🔌
  • $bool = $obj->ipc_disabled — checks whether IPC is disabled 🧐
  • $stack = $obj->stack — gets the one true hub stack 🥞
  • $formatter = $obj->formatter — gets the global formatter. By default this is the 'Test2::Formatter::TAP' package 💖 This could be any package that implements the write() method, and it can also be an instantiated object 🎀
  • $bool = $obj->formatter_set() — checks whether a formatter has been set ✅
  • $obj->add_formatter($class) and $obj->add_formatter($obj) — adds a formatter. The most recently added formatter becomes the global one during initialization. If a formatter is added after initialization has occurred, a warning gets generated 📢:
"Formatter $formatter loaded too late to be used as the global formatter"
  • $obj->set_add_uuid_via(sub { ... }) and $sub = $obj->add_uuid_via() — this lets you provide a UUID generator 🌈 If one is provided, UUIDs get attached to all events, hubs, and contexts. Super useful for storing, tracking, and linking these objects 🔗

The sub you provide should always return a unique identifier. Most things will expect a proper UUID string, however nothing in Test2::API enforces this 🫠

The sub will receive exactly 1 argument: the type of thing being tagged — 'context', 'hub', or 'event'. In the future, additional things may be tagged, in which case new strings will be passed in. These are purely informative — you can (and usually should) ignore them 💅

🌸 SOURCE 🌸

the source code repository for Test2 lives at <https://github.com/Test-More/test-more/> — go be nosy, bestie 🕵️‍♀️

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org> 🫡

💜 AUTHORS 💜

Chad Granum <exodist@cpan.org> 💜

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/>

okay and that's the whole thing bestie, no cap 💖 this page shipped as part of perl v5.44.0 and it's dated 2026-10-17 ✨ go forth and... not use this package directly, because again, we said not to 🙈 mwah 💅🎀🦋

📦 where this page comes from