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

💅 NAME 💅

okay bestie, welcome to Test2::Manual::Tooling::Testing(3pm) — the manual page for Test2::Manual::Tooling::Testing — and it is literally a tutorial on how to test your testing tools. Periodt. 🫶

🌸 DESCRIPTION 🌸

okay so back in the day, testing your test tools was a whole complicated and difficult situation. The old tools such as Test::Tester and Test::Builder::Tester were limited, and fragile, ngl. 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. It is giving main character energy fr fr.

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

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

[
    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 is literally the place. 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/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/

okay that’s the whole page, bestie — love u, bye! 💖 This one’s from the Perl Programmers Reference Guide, perl v5.42.3, dated 2026-11-03. Slay. 🎀