TEST2::MANUAL::TOOLING::TESTING(3perl)

📦
version 5.44.0 · 8 versions
, in arch rolling

🎀 Test2::Manual::Tooling::Testing 💖

okay bestie, so this is a page from the Perl Programmers Reference Guide, and it's literally the tutorial on how to test your testing tools. Yes, that's a real thing. Testing the thing that tests the thing. It's tests all the way down and honestly? Iconic.

✨ NAME ✨

Test2::Manual::Tooling::Testing — a whole tutorial on how to test your testing tools. fr fr.

🌸 DESCRIPTION 🌸

so like, back in the day, testing your test tools was a whole situation. messy, fragile, lowkey painful. the old stuff like Test::Tester and Test::Builder::Tester? limited. fragile. it's giving "we tried our best in 2009."

Test2, on the other hand, was designed from the very start to be easy to test. like, they built the house with the testability already in the walls. this tutorial shows you how. let's go 💅

👑 THE HOLY GRAIL OF TESTING YOUR TOOLS 👑

the key to making Test2 easily testable (especially when you compare it to Test::Builder) is the "intercept" function. she's the moment. the main character. periodt.

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. any of them. go off.

No events or contexts generated within the intercept codeblock will have any effect on the outside testing state. none. zero. the "intercept" function completely isolates the tools called within. it's a little bubble 🫧

note bestie: Plugins and things that affect global API state may not be fully isolated. "intercept" is intended specifically for event isolation. so like, event-wise it's a vault, but global API state can still leak. iykyk.

the "intercept" function returns an arrayref containing all the events that were generated within the codeblock. and now you can make literally any assertions you want about the events you expected your tools to generate. chef's kiss.

[
    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 in Test2::Manual::Anatomy::Event. go read it. it's not optional if you want to actually understand what you're looking at. 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. the freshest. the newest. the it-girl of event testing.

to really understand these, you should familiarize yourself with Test2::Manual::Anatomy::Event. and listen — if you are going to be writing anything more than the most simple of tools, you should know how events work. no shortcuts, bestie.

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

💖 Test2::Tools::HarnessTester

Test2::Tools::HarnessTester can export the summarize_events() tool. this one lets you run your event arrayref through Test2::Harness so you can get a pass/fail summary. so convenient.

my $summary = summarize_events($events);

and 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. they will still work, but they are no longer the recommended way to test your tools. it's giving legacy. it's giving "she still shows up but she's not on the invite list anymore."

Test2::Tools::Compare exports a handful of extras to help test events. a little grab bag.

  • event $TYPE => ... — use this in an array check against $events to check for a specific type of event with the properties you specify. like a vibe check but for event types.
  • fail_events $TYPE => ... — use this when you expect a failing assertion of $TYPE. it will automatically check that the next event following it is a diagnostics message with the default failure text. auto-detective behaviour, we love her.
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. so heads up, this one has a known gap 😭

🦋 SEE ALSO 🦋

  • Test2::Manual — the primary index of the manual. your map. your little directory. go there. 🌸

🌟 SOURCE 🌟

the source code repository for Test2-Manual can be found at https://github.com/Test-More/test-more/. go star it, bestie. 💖

👑 MAINTAINERS 👑

  • Chad Granum <exodist@cpan.org>

💜 AUTHORS 💜

  • Chad Granum <exodist@cpan.org>

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. slay.

See http://dev.perl.org/licenses/

and that's the whole page, bestie!! this was perl v5.44.0, dated 2026-10-17, and yeah the footer says Test2:...Testing(3perl) because manpage footers are long and dramatic like that. now go test your tests 💅✨

📦 where this page comes from