Test2::Manual::Tooling::Testing(3) User Contributed Perl Documentation
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 affect 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(3) - Primary index of the manual.
SOURCE
The source code repository for Test2-Manual 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/
perl v5.34.3 2025-03-30
Test2::Manual::Tooling::Testing(3)
test-simple 1.302.210 - Generated Tue Apr 1 18:54:37 CDT 2025