Test2:...::Hubs(3perl)

📦
version 5.44.0 · 8 versions
, in arch rolling

💖 Test2::Manual::Anatomy::Hubs 💖

okay bestie, welcome to the internals lore of Test2::Manual::Anatomy::Hubs ✨ this is the manual page that spills all the tea about the hub stack and the hubs living inside it. It explains why we even have a stack, and when you should be adding hubs to it or yeeting them off it. 🫶

🌸 DESCRIPTION 🌸

This doc is your backstage pass to the hub stack and every hub it's holding. We're gonna talk about why a stack exists at all, and when it's time to add hubs to it or take hubs away. it's giving "VIP tour of the plumbing" and honestly? iconic. 💅

🧚 WHAT IS A HUB? 🧚

So here's the vibe: Test2 is an event system. 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 events so it can record that change in state. And every single event should eventually reach a destination hub. no event left behind fr fr. 💖

The base hub is Test2::Hub. All hub classes should inherit from the base hub class. The base hub class hands you several hooks that let you monitor or modify events. Hubs are also responsible for forwarding events to the output formatter. so yes, hub = main character energy 👑

🌈 WHY DO WE HAVE A HUB STACK? 🌈

There are cases where it makes sense to have more than one hub. like, more than one is genuinely the move:

  • subtests — In Test2, subtests are implemented using the hub stack. When you start a subtest, a new Test2::Hub::Subtest instance is 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 will remove the new hub and send a final subtest event to the parent hub. 🎀
  • testing your test tools — Test2::API::intercept() is implemented using the hub stack. The Test2::API::intercept() function will add an Test2::Hub::Interceptor instance to the stack, and any calls to Test2::API::context() will find the new hub and send it all events. The intercept hub is special in that it has no connection to the parent hub, and usually does not have a formatter. lowkey mysterious, highkey useful. 🕵️♀️

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

Any time you want to intercept or block events from affecting the test state. 🛑

Adding a new hub is essentially a way to create a sandbox where you have absolute control over what events do. Adding a new hub insures that the main test state will not be affected. periodt. 💅

🔥 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". go get your stack bestie, it's waiting. 🫶

👑 WHAT ABOUT THE ROOT HUB? 👑

The root hub is created automatically as needed. A call to "Test2::API::test2_stack->top()" will create the root hub if it does not already exist. it literally spawns itself, main character behaviour ngl. ✨

💀 HOW DO HUBS HANDLE IPC? 💀

If the IPC system (Test2::IPC) was not loaded, then IPC is not handled at all. Forking or creating new threads without the IPC system can cause unexpected problems. 😭

⚠️ for real, do not fork or spin up new threads without the IPC system unless you want chaos. it's giving nightmare fuel.

All hubs track the PID and Thread ID that was current when they were created. If an event is 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. 🦋

🌸 SEE ALSO 🌸

  • Test2::Manual — Primary index of the manual. go read the whole series bestie, it's a saga. 📚

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

and that's the whole page bestie!! 🎀 this was Test2: ... ::Hubs(3perl) — shipped as part of perl v5.44.0, dated 2026-10-17, from the Perl Programmers Reference Guide. slay, go write some hubs. 💖✨🦋

📦 where this page comes from