Test2::...Grabber(3pm)

📦
version 5.42.3 · 16 versions
, in alpine 3.24

💖 NAME 💖

Bestie, this is Test2::Util::Grabber — the object that temporarily intercepts all the events for you. Like a little event trap. A vibe checkpoint for your test output. ✨

🌸 DESCRIPTION 🌸

Okay so the moment this object is created, it starts intercepting and stashing all events sent to the shared Test2::Hub object. It's giving bouncer at the club, but for test events. 🎀

Once the object is destroyed? Events go right back to being sent to the shared hub. Business as usual. No cap.

✨ SYNOPSIS ✨

use Test2 qw/Core 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");

# Same as flush, except it destroys the grab object.
my $events_b = $grab->finish;

So after you call finish() the grab object is destroyed and $grab is set to undef. $events_a is an arrayref with the first two events. $events_b is an arrayref with the second two events. Cute, right? 💅

🦋 EXPORTS 🦋

  • $grab = grab() — this lets you intercept all events for a section of code without adding anything to your call stack. Highkey useful for things that are sensitive to changes in the stack depth. 👑
my $grab = grab();
    ok(1, 'foo');
    ok(0, 'bar');

# $grab is magically undef after this.
my $events = $grab->finish;

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

When you call finish() the $grab object will automagically undef itself — but only for the reference used in the method call. If you have other references to the $grab object, they will not be set to undef. Important!! Don't get caught lacking. 😭

If the $grab object is destroyed without calling finish(), it will automatically clean up after itself and restore the parent hub. Self-care icon behavior.

{
    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 one test. You can turn enforcement back one 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. Consider yourself warned bestie 🫶

💜 METHODS 💜

  • $grab = $class->new() — create a new grab object. It immediately starts intercepting events. Main character energy from the jump. ⭐
  • $ar = $grab->flush() — get an arrayref of all the events so far, clearing the grab object's internal list. Poof, gone, but you got the receipts. 🧚
  • $ar = $grab->events() — get an arrayref of all events so far. Does not clear the internal list. The events stay put. 🙈
  • $ar = $grab->finish() — get an arrayref of all the events, then destroy the grab object. It's the grand finale. 💀
  • $hub = $grab->hub() — get the hub that is used by the grab event. That's the one right there. 🔥

🌈 ENDING BEHAVIOR 🌈

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 one test. You can turn enforcement back one 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 like… don't be surprised when extra events show up. It's giving consequences. 🍓

👀 SEE ALSO 👀

  • Test2::Tools::Intercept — accomplish the same thing, but using blocks instead. Same slay, different outfit. 💖

🎀 SOURCE 🎀

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

🌸 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 thing, bestie. This page is from perl v5.42.3, dated 2026-11-03, and it lives under Test2::...Grabber(3pm). Iconic. Periodt. 🫶💜

📦 where this page comes from