Test2::...xception(3)

🌸 NAME 🌸

okay so the header is doing the truncated Test2::...xception(3) thing, and this page is part of User Contributed Perl Documentation — the actual module is Test2::Tools::Exception, and it's literally Test2 based tools for checking exceptions. 💅

💖 DESCRIPTION 💖

so this is the Test2 implementation of code you use to test exceptions. It's similar to Test::Fatal, but it intentionally does much less — and that's the whole point, bestie. ✨

✨ SYNOPSIS ✨

copy-paste this energy:

use Test2::Tools::Exception qw/dies lives/;

like(
    dies { die 'xxx' },
    qr/xxx/,
    "Got exception"
);

ok(lives { ... }, "did not die") or note($@);

🎀 EXPORTS 🎀

All subs are exported by default.

• $e = dies { ... } — this traps any exception the codeblock throws. If no exception is thrown, the sub returns undef. If an exception is thrown, it gets returned. This function preserves $@; it will not be altered from its value before the sub is called. 🫶
• $bool = lives { ... } — this traps any exception thrown in the codeblock. It returns true when there is no exception, and false when there is. $@ is preserved from before the sub is called when there is no exception. When an exception is trapped, $@ will have the exception so you can look at it. 👀
• $bool = try_ok { ... } and $bool = try_ok { ... } "Test Description" — this runs the code block, trapping any exception. If there is no exception, a passing event will be issued. If the test fails, a failing event will be issued, and the exception will be reported as diagnostics. 🧚

Note: this function does not preserve $@ on failure. It will be set to the exception the codeblock throws — that's by design, so you can obtain the exception if you want it. 💀

🦋 DIFFERENCES FROM TEST::FATAL 🦋

Test::Fatal sets $Test::Builder::Level such that failing tests inside the exception block will report to the line where exception() is called. The author disagrees with this and thinks the actual line of the failing test is more important. Ultimately, though, Test::Fatal cannot be changed, and people probably already depend on that behavior. no cap. 🙈

🔥 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/

---

okay bestie, this page's footer says perl v5.42.0, dated 2025-07-28, and signs off as Test2::...xception(3) — iconic. 💅✨