NAME

       Test2::Manual::Tooling::Testing - Tutorial on how to test your testing tools.

DESCRIPTION

       Testing your test tools used to be a complex and difficult prospect. The old tools such as Test::Tester
       and Test::Builder::Tester were limited, and fragile. Test2 on the other hand was designed from the very
       start to be easily tested! This tutorial shows you how.

THE HOLY GRAIL OF TESTING YOUR TOOLS

       The key to making Test2 easily testable (specially when compared to Test::Builder) is the "intercept"
       function.

           use Test2::API qw/intercept/;

           my $events = intercept {
               ok(1, "pass");
               ok(0, "fail");

               diag("A diag");
           };

       The intercept function lets you use any test tools you want inside a codeblock.  No events or contexts
       generated within the intercept codeblock will have any effect on the outside testing state. The
       "intercept" function completely isolates the tools called within.

       Note: Plugins and things that effect global API state may not be fully isolated. "intercept" is intended
       specifically for event isolation.

       The "intercept" function will return an arrayref containing all the events that were generated within the
       codeblock. You can now make any assertions you want about the events you expected your tools to generate.

           [
               bless({...}, 'Test2::Event::Ok'),   # pass
               bless({...}, 'Test2::Event::Ok'),   # fail
               bless({...}, 'Test2::Event::Diag'), # Failure diagnostics (not always a second event)
               bless({...}, 'Test2::Event::Diag'), # custom 'A diag' message
           ]

       Most test tools eventually produce one or more events. To effectively verify the events you get from
       intercept you really should read up on how events work Test2::Manual::Anatomy::Event. Once you know about
       events you can move on to the next section which points you at some helpers.

ADDITIONAL HELPERS

   Test2::Tools::Tester
       This is the most recent set of tools to help you test your events. To really understand these you should
       familiarize yourself with Test2::Manual::Anatomy::Event. If you are going to be writing anything more
       than the most simple of tools you should know how events work.

       The Test2::Tools::Tester documentation is a good place for further reading.

   Test2::Tools::HarnessTester
       The Test2::Tools::HarnessTester can export the "summarize_events()" tool.  This tool lets you run your
       event arrayref through Test2::Harness so that you can get a pass/fail summary.

           my $summary = summarize_events($events);

       The summary looks like this:

           {
               plan       => $plan_facet,         # the plan event facet
               pass       => $bool,               # true if the events result in a pass
               fail       => $bool,               # true if the events result in a fail
               errors     => $error_count,        # Number of error facets seen
               failures   => $failure_count,      # Number of failing assertions seen
               assertions => $assertion_count,    # Total number of assertions seen
           }

   Test2::Tools::Compare
       DEPRECATED These tools were written before the switch to faceted events.  These will still work, but are
       no longer the recommended way to test your tools.

       The Test2::Tools::Compare library exports a handful of extras to help test events.

       event $TYPE => ...
           Use  in  an array check against $events to check for a specific type of event with the properties you
           specify.

       fail_events $TYPE => ...
           Use when you expect a failing assertion of $TYPE. This will automatically check that the  next  event
           following it is a diagnostics message with the default failure text.

           Note:  This  is outdated as a single event may now possess both the failing assertion AND the failing
           text, such events will fail this test.

SEE ALSO

       Test2::Manual - Primary index of the manual.

SOURCE

       The source code repository for Test2-Manual 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.36.0                                       2023-10-26               Test2::Manual::Tooling::Testing(3pm)