TEST2::MANUAL::ANATOMY::CONTEXT(3perl)

📦
version 5.44.0 · 8 versions
, in arch rolling

💖 NAME 💖

Test2::Manual::Anatomy::Context — the internals tea on the Context objects, bestie. Like, the documentation for the documentation-adjacent guts. 🫶

🌸 DESCRIPTION 🌸

Okay so this doc is literally just here to explain how the Test2::API::Context object works. That's it. That's the whole vibe. ✨

👑 WHAT IS THE CONTEXT OBJECT? 👑

The context object is one of the key components of Test2, no cap — it's the thing that makes so many features possible that would otherwise be straight-up impossible. 🦋

The flow is iconic and it never changes:

  • Every test tool starts by getting a context
  • ...does all its work in between
  • ...and ends by releasing the context

The context instance is the primary interface for sending events to the Test2 stack. And finally — and this is the part that's lowkey critical for debugging — the context system is responsible for tracking what file and line number a tool operates on. Very main character of it. 💅

🔥 PRIMARY INTERFACE FOR TEST TOOLS 🔥

Nearly every Test2 based tool should start by calling:

$ctx = Test2::API::context()

...to get a context object, and should end by calling:

$ctx->release()

Once a tool has its context object it can call methods on the object to send events or have other effects. Nearly everything a test tool needs to do should be done through the context object. Periodt. 🎀

🧚 TRACK FILE AND LINE NUMBERS FOR ERROR REPORTING 🧚

When you call Test2::API::Context a new context object will be returned. Here's the rules, bestie:

  • If there is already a context object in effect (from a different point in the stack) you will get a clone of the existing one.
  • If there is not already a current context then a completely new one will be generated.

When a new context is generated Test2 will determine the file name and line number for your test code — these will be used when reporting any failures. 📍

Typically the file and line number will be determined using caller() to look at your tools caller. The $Test::Builder::Level will be respected if detected, but — ngl — that's discouraged in favor of just using context objects at every level.

When calling Test2::API::Context() you can specify the "level => $count" arguments if you need to look at a deeper caller. 🔍

🍓 PRESERVE $?, $!, $^E AND $@ 🍓

When you call Test2::API::context() the current values of $?, $!, $^E, and $@ are stored in the context object itself. Whenever the context is released the original values of these variables will be restored. This protects the variables from any side effects caused by testing tools. Protecting the babies, fr fr. 🙈

⭐ FINALIZE THE API STATE ⭐

Test2::API works via a hidden singleton instance of Test2::API::Instance. That singleton has some state that is not set in stone until the last possible minute. And when is the last possible minute, you ask? It happens to be the first time a context is acquired. Iconic timing.

The state includes:

  • IPC instance
  • Formatter class
  • Root PID
  • etc.

🌈 FIND/CREATE THE CURRENT/ROOT HUB 🌈

Test2 has a stack of hubs, and the stack can be accessed via Test2::API::test2_stack. When you get a context it will find the current hub — and if there is no current hub then the root one will be initialized. 🫶

💜 PROVIDE HOOKS 💜

There are hooks that run when contexts are created, found, and released. See Test2::API for details on these hooks and how to use them. Go get your hooks, bestie.

✨ SEE ALSO ✨

  • Test2::Manual — Primary index of the manual.

💀 SOURCE 💀

The source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/.

👑 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 http://dev.perl.org/licenses/

okay bestie that's the whole thing, you ate it, no crumbs left 💅✨

This was perl v5.44.0, dated 2026-10-17 — and that's the Test2::Manual::Anatomy::Context page, signing off, mwah 🫶💖

📦 where this page comes from