Test::S...n::Grab(3)

📦
version 1.302027 · 2 versions
, in fedora 43

💖 Test::Stream::Plugin::Grab — the manual, but make it make sense 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section, and it's literally called Test::S...n::Grab(3) — yes the name is giving "my terminal got shy and elided the middle" but it's fr the grab plugin. Let's get into it. ✨

💀 DEPRECATED 💀

Not to be dramatic but… this whole distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow.

If you're trying to convert your old stuff over, go look at Test::Stream::Manual::ToTest2 — that's the conversion guide, iykyk. 🫶

🌸 DESCRIPTION 🌸

The way this works is SO clean actually:

  • The moment you create one of these objects, it intercepts and stashes all events sent to the shared Test::Stream::Hub object. 👑
  • The moment the object gets destroyed, events go right back to being sent to the shared hub like nothing ever happened.

It's giving "temporary bubble of chaos, then everything's normal again." 🦋

✨ SYNOPSIS ✨

Here's the vibe, verbatim:

use Test::Stream 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 here's the tea ☕ — after you call finish(), the grab object is destroyed and $grab is set to undef. Meanwhile:

  • $events_a is an arrayref with the first 2 events. 🍓
  • $events_b is an arrayref with the second 2 events. 🧚

🎀 EXPORTS 🎀

$grab = grab()

This one is the main character fr. It lets you intercept all events for a section of code without adding anything to your call stack. Lowkey iconic 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 2 events.");

Okay so when you call finish(), the $grab object will automagically undef itself — but ⚠️ only for the reference used in the method call. If you've got other references to the $grab object kicking around, those will not be undef'd. Bestie they're staying. 🙈

If the $grab object gets destroyed without calling finish(), it will automatically clean up after itself and restore the parent hub:

{
    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. 👀

🌈 METHODS 🌈

  • $grab = $class->new() — Create a new grab object, and it immediately starts intercepting events. No warmup, no hesitation, straight to it. 🔥
  • $ar = $grab->flush() — Get an arrayref of all the events so far, and it clears the grab object's internal list. 💫
  • $ar = $grab->events() — Get an arrayref of all events so far, but it does not clear the internal list. The events are staying, periodt. 🌸
  • $ar = $grab->finish() — Get an arrayref of all the events, then destroy the grab object. It's the farewell tour. 👋
  • $hub = $grab->hub() — Get the hub that is used by the grab event. 🛸

💜 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 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. (Yes, same tea as before — the manpage said it twice and we're not skipping anything. 🫡)

👀 SEE ALSO 👀

  • Test::Stream::Plugin::Intercept — Accomplish the same thing, but using blocks instead. Same energy, different shape. ✨

📦 SOURCE 📦

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/. Go be nosy, bestie. 🦋

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

🌟 AUTHORS 🌟

Chad Granum <exodist@cpan.org>

Copyright 2015 Chad Granum <exodist7@gmail.com>.

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/

🚨 POD ERRORS 🚨

Hey! The above document had some coding errors, which are explained below:

  • Around line 140:
    • '=item' outside of any '=over'
  • Around line 178:
    • You forgot a '=back' before '=head1'
Not us being messy in the POD 🫣 but hey, we're reporting the errors exactly as they were found. Fidelity, babes. 💅

And that's the whole page, bestie — written for perl v5.42.0, dated 2025-07-25, filed under Test::S...n::Grab(3). Slay, go intercept some events. 💖✨🎀

📦 where this page comes from