Test2::...:Tester(3pm)

🎀 Test2::Tools::Tester 💅

okay bestie, welcome to Test2::Tools::Tester — part of the Perl Programmers Reference Guide, and honestly? it's the tool you reach for when you need to test your other testing tools. yes, we're going meta, we're going icon status, periodt ✨

---

🌸 NAME 🌸

Test2::Tools::Tester — Tools to help you test other testing tools. that's it, that's the vibe 🫶

---

🦋 DESCRIPTION 🦋

so this is literally a collection of tools that are useful when testing other test tools. it's giving backstage pass, it's giving QA-for-the-QA. lowkey essential if you're building test infrastructure and you want to make sure your events are coming out exactly right 💖

---

✨ SYNOPSIS ✨

use Test2::Tools::Tester qw/event_groups filter_events facets/;

use Test2::Tools::Basic qw/plan pass ok/;
use Test2::Tools::Compare qw/is like/;

my $events = intercept {
    plan 11;

    pass('pass');
    ok(1, 'pass');

    is(1, 1, "pass");
    like(1, 1, "pass");
};

# Grab events generated by tools in Test2::Tools::Basic
my $basic = filter $events => 'Test2::Tools::Basic';

# Grab events generated by tools in Test2::Tools::Basic;
my $compare = filter $events => 'Test2::Tools::Compare';

# Grab events generated by tools named 'ok'.
my $oks = filter $events => qr/.*::ok$/;

my $grouped = group_events $events;
# Breaks events into this structure:
{
    '__NA__' => [ ... ],
    'Test2::Tools::Basic' => {
        '__ALL__' => [ $events->[0], $events->[1], $events->[2] ],
        plan => [ $events->[0] ],
        pass => [ $events->[1] ],
        ok => [ $events->[2] ],
    },
    Test2::Tools::Compare => { ... },
}

# Get an arrayref of all the assert facets from the list of events.
my $assert_facets = facets assert => $events;
# [
#   bless({ details => 'pass', pass => 1}, 'Test2::EventFacet::Assert'),
#   bless({ details => 'pass', pass => 1}, 'Test2::EventFacet::Assert'),
# ]

# Same, but for info facets
my $info_facets = facets info => $events;

like?? look at her go 😭 she's so organized 🧚

---

💜 EXPORTS 💜

No subs are exported by default. ngl you gotta ask for what you want, respect the boundaries bestie 🙈

$array_ref = filter $events => $PACKAGE

$array_ref = filter $events => $PACKAGE1, $PACKAGE2

$array_ref = filter $events => qr/match/

$array_ref = filter $events => qr/match/, $PACKAGE

this function takes an arrayref of events as the first argument. everything after that has to either be a package name or a regex — those are your only options, no cap. any event that's generated by a tool in any of the packages, or by a tool that matches any of the regexes, gets returned to you in an arrayref. it's the ultimate event bouncer 💅

$grouped = group_events($events)

this function iterates all the events in the argument arrayref and splits them into groups. the resulting data structure is:

{ PACKAGE => { SUBNAME => [ $EVENT1, $EVENT2, ... }}

if the package of an event isn't known, it gets put into an arrayref under the '__NA__' key at the root of the structure. if a sub name isn't known, it will typically go under the '__ANON__' key, under the package name. the mystery bins, basically 🕵️‍♀️

in addition there's an '__ALL__' key under each package which stores all of the events sorted into that group. catch-all icon behavior 👑

a more complete example:

{
    '__NA__' => [ $event->[3] ],
    'Test2::Tools::Basic' => {
        '__ALL__' => [ $events->[0], $events->[1], $events->[2] ],
        plan => [ $events->[0] ],
        pass => [ $events->[1] ],
        ok => [ $events->[2] ],
    },
}

$arrayref = facets TYPE => $events

this function compiles a list of all facets of the specified type that are found in the arrayref of events. here's the cute part: if the facet has a "Test2::EventFacet::TYPE" package available, then the facet gets constructed into an instance of that class — otherwise it's just left as a hashref. Facet Order is preserved, so nothing gets shuffled around behind your back 🎀

my $assert_facets = facets assert => $events;
# [
#   bless({ details => 'pass', pass => 1}, 'Test2::EventFacet::Assert'),
#   bless({ details => 'pass', pass => 1}, 'Test2::EventFacet::Assert'),
# ]

---

🌈 SOURCE 🌈

the source code repository for Test2-Suite lives at https://github.com/Test-More/test-more/. go visit her, she's lovely 💖

---

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

---

fr fr this is the whole page, nothing skipped, every flag and key and facet accounted for — we do not cut corners in this group chat 💅

and that's a wrap, bestie!! this page came to you courtesy of perl v5.42.3, dated 2026-11-03 — go forth and test your tests, mwah 🫶💜🌸