NAME

       Test2::Tools::Tester - Tools to help you test other testing tools.

DESCRIPTION

       This is a collection of tools that are useful when testing other test tools.

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 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;

EXPORTS

       No subs are exported by default.

       $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. All additional arguments must either
           be  a  package name, or a regex. Any event that is generated by a tool in any of the package, or by a
           tool that matches any of the regexes, will be returned in an arrayref.

       $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 is not known it will be put into and arrayref under the '__NA__' key at
           the root of the structure. If a sub name is not known it will typically go under the  '__ANON__'  key
           in under the package name.

           In  addition  there is an '__ALL__' key under each package which stores all of the events sorted into
           that group.

           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 will compile a list of all facets of the specified type that are found in the  arrayref
           of  events.  If  the  facet  has a "Test2::EventFacet::TYPE" package available then the facet will be
           constructed into an instance of the class, otherwise  it  is  left  as  a  hashref.  Facet  Order  is
           preserved.

               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 can be found at https://github.com/Test-More/Test2-Suite/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2018 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/

perl v5.40.1                                       2025-04-14                        Test2::Tools::Tester(3perl)