Test2::...y::Hubs(3pm)

📦
version 5.42.3 · 16 versions
, in alpine 3.24

🦋 NAME 🦋

okay so bestie, this is Test2::Manual::Anatomy::Hubs (that's the 3pm one, Perl Programmers Reference Guide section, iykyk) — and it's literally the internals doc for the hub stack and all the hubs living inside it. ✨

💜 DESCRIPTION 💜

This doc breaks down the hub stack and the hubs it's holding, fr. It explains why we even have a stack in the first place, and when you should be adding hubs to it or yeeting them out. no gatekeeping here 🫶

🌸 WHAT IS A HUB? 🌸

So Test2 is an event system, right? Tools generate events, and then those events get processed to modify the testing state (think: number of tests, number of failures, etc). The hub is the one responsible for receiving and processing those events so the state change actually gets recorded. All events should eventually reach a destination hub. periodt. 💅

The base hub is Test2::Hub. Every hub class should inherit from that base hub class — that's the whole vibe. The base hub class hands you several hooks so you can monitor or modify events, and hubs are also responsible for forwarding events along to the output formatter. multitasking icon behavior 👑

🔥 WHY DO WE HAVE A HUB STACK? 🔥

Because sometimes one hub just isn't the moment, and it genuinely makes sense to have more than one:

  • subtests — in Test2, subtests are implemented using the hub stack. When you start a subtest, a new Test2::Hub::Subtest instance gets created and pushed to the stack. Once that's done, all calls to Test2::API::context will find the new hub and send all events to it. When the subtest tool is complete it removes the new hub, and sends a final subtest event to the parent hub. clean exit, no crumbs 🧚
  • testing your test tools — Test2::API::intercept() is also implemented using the hub stack. The Test2::API::intercept() function adds a Test2::Hub::Interceptor instance to the stack, and any calls to Test2::API::context() will find the new hub and send it all the events. The intercept hub is special because it has no connection to the parent hub, and usually does not have a formatter. it's giving independent main character energy 😭

✨ WHEN SHOULD I ADD A HUB TO THE STACK? ✨

Any time you wanna intercept or block events from affecting the test state, bestie. Adding a new hub is basically your way of creating a sandbox where you have absolute control over what events do. And adding a new hub insures that the main test state will not be affected. protect the peace 🫶

🎀 WHERE IS THE STACK? 🎀

The stack is an instance of Test2::API::Stack. You can access the global hub stack using Test2::API::test2_stack. she's right there 💅

🌈 WHAT ABOUT THE ROOT HUB? 🌈

The root hub is created automatically as needed — no manual labor required. A call to Test2::API::test2_stack->top() will create the root hub if it does not already exist. it just appears ✨

💀 HOW DO HUBS HANDLE IPC? 💀

If the IPC system (Test2::IPC) was not loaded, then IPC is just… not handled at all. nada. And heads up: forking or creating new threads without the IPC system can cause unexpected problems. not a vibe, be careful 🙈

All hubs track the PID and Thread ID that was current when they were created. So if an event gets sent to a hub in a new process/thread, the hub will detect this and try to forward the event along to the correct process/thread. This is accomplished using the IPC system. she knows where she came from 🔥

🍓 SEE ALSO 🍓

  • Test2::Manual — Primary index of the manual. start here bestie, it's the map 🗺️

⭐ SOURCE ⭐

The source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/. go be nosy, it's encouraged 💖

👑 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 that's the whole thing, no cap 💅 this page is perl v5.42.3 and it's dated 2026-11-03 — screenshot it, bookmark it, memorize it, slay ✨🦋🎀

📦 where this page comes from