<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Tools/Tester.md. Do not edit. -->

```{index} single: Test2::Tools::Tester
```

# 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

```perl
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:

    ```perl
    { 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:

    ```perl
    {
        '__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.

    ```perl
    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/test-more/`.

## 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/`