Test2:...::Grab(3perl)

✨ NAME ✨

Test2::Tools::Grab — the way to temporarily intercept ALL the events without adding a scope level 💅 (this page lives in the Test2:...::Grab(3perl) section of the manual, iykyk)

🌸 DESCRIPTION 🌸

Okay so bestie, this package hands you a function that returns an object, and that object grabs every event for you. Then the moment that object gets destroyed, events go right back to being sent to the main hub like nothing ever happened. It's giving "borrow the spotlight for a sec, then give it back" 👑

🦋 SYNOPSIS 🦋

use Test2::Tools::Grab;

my $grab = grab();

# Generate some events, they are intercepted.
ok(1, "pass");
ok(0, "fail");

my $events_a = $grab->flush;

# Generate some more events, they are intercepted.
ok(1, "pass");
ok(0, "fail");

my $events_b = $grab->finish;

💖 EXPORTS 💖

• $grab = grab() — this one lets you intercept all the events happening in a section of your code without adding anything to your call stack. Which, fr fr, is the whole point: it's useful for things that are sensitive to changes in the stack depth.

my $grab = grab();
    ok(1, 'foo');
    ok(0, 'bar');

my $events = $grab->finish;

is(@$events, 2, "grabbed 2 events.");

Now here's the cute part 🎀 — if the $grab object gets destroyed without calling finish(), it will automatically clean up after itself and restore the parent hub. It literally tidies up on its own, no cap.

{
    my $grab = grab();
    # Things are grabbed
}
# Things are back to normal

By default the hub used has no_ending set to true. What does that do? It prevents the hub from enforcing that you issued a plan and ran at least 1 test. So chill. But if you want the enforcement back, you can turn it back on like this:

$grab->hub->set_no_ending(0);

Heads up bestie: with no_ending turned off, finish will run the post-test checks to enforce the plan and that tests were run. In many cases this will result in additional events in your events array. So like, expect extra guests at the party 😭

👀 SEE ALSO 👀

• Test2::Util::Grabber — the object constructed and returned by this tool.

⭐ SOURCE ⭐

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

---

🌈 MAINTAINERS 🌈

Chad Granum <exodist@cpan.org>

👑 AUTHORS 👑

Chad Granum <exodist@cpan.org>

💜 COPYRIGHT 💜

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 a wrap, bestie 💖 this was perl v5.44.0, dated 2026-10-17, straight from the Test2:...::Grab(3perl) manual page — slay, go grab some events ✨