TEST2::TOOLS::GRAB(3pm)

💖 NAME 💖

Okay so bestie, welcome to Test2::Tools::Grab(3pm) — the little Perl manual page with main character energy. It's literally: Test2::Tools::Grab — Temporarily intercept all events without adding a scope level. No cap, that's the whole vibe: snatch events for a bit, then let them go. 💅

🌸 DESCRIPTION 🌸

This package provides a function that returns an object that grabs all events. Like, it catches them all. Once the object is destroyed, events will once again be sent to the main hub. Periodt. ✨

✨ SYNOPSIS ✨

The way this slays:

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 lets you intercept all events for a section of code without adding anything to your call stack. It's giving "stack-depth-sensitive safe", and that is highkey 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.");

If the $grab object is destroyed without calling finish(), it will automatically clean up after itself and restore the parent hub. Not me being dramatic, that's just what it does. 😭

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

By default the hub used has no_ending set to true. This will prevent the hub from enforcing that you issued a plan and ran at least 1 test. You can turn enforcement back on like this:

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

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 yeah, your events array might get extra guests at the party — that's expected. 🔥

🦋 SEE ALSO 🦋

• Test2::Util::Grabber — the object constructed and returned by this tool. Iconic little helper, iykyk. 👑

🌈 SOURCE 🌈

The source code repository for Test2 can be found at https://github.com/Test-More/test-more/. Go peek if you're nosy in the best way. 🫶

👑 MAINTAINERS 👑

• Chad Granum <exodist@cpan.org> — maintaining the whole situation. Fr fr. 🌟

🧚 AUTHORS 🧚

• Chad Granum <exodist@cpan.org> — author energy, literally. ✨

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

That's the whole page, bestie! 💅 Signed with love from Test2::Tools::Grab(3pm) — perl v5.42.3, dated 2026-11-03. ✨🎀