TEST2::TOOLS::EXCEPTION(3perl)

✨ NAME ✨

Test2::Tools::Exception — bestie, it's the Test2-based toolkit for checking exceptions 💖 (manual name Test2:...ception(3perl) if you're keeping receipts)

---

🦋 DESCRIPTION 🦋

Okay so this is the Test2 implementation of the code you use to test exceptions. It's giving Test::Fatal, but make it intentionally do much less. That's the whole vibe. No extra baggage, no surprise features, just the exception-checking essentials and nothing more, periodt 💅

---

🌸 SYNOPSIS 🌸

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

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

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

Look at that. Clean. Iconic. No cap 🎀

---

👑 EXPORTS 👑

All subs are exported by default. You don't gotta ask, they just show up. Slay.

• $e = dies { ... } — This one traps any exception that the codeblock throws. If nothing gets thrown, the sub returns undef. If something does get thrown, that exception gets returned to you. And here's the important part bestie: it preserves $@ — it will not be altered from whatever its value was before the sub got called. Your $@ is safe, I would never do that to you 🫶
• $bool = lives { ... } — This traps any exception thrown in the codeblock and hands you back a boolean. True when there's no exception, false when there is. When there's no exception, $@ is preserved from before the sub was called. When an exception is trapped, $@ will hold that exception so you can peek at it yourself. It's giving "here's the tea, go read it" ☕
• $bool = try_ok { ... }
• $bool = try_ok { ... } "Test Description" — This runs the code block and traps any exception. If there's no exception, a passing event gets issued. If the test fails, a failing event gets issued and the exception gets reported as diagnostics. Two forms: with a test description string or without, your call 💖

Note: This function does not preserve $@ on failure — it will be set to the exception the codeblock throws. That's <em>by design</em> so you can obtain the exception if you want it. Not a bug, it's a feature, iykyk 💀

---

🔥 DIFFERENCES FROM TEST::FATAL 🔥

Okay so Test::Fatal sets $Test::Builder::Level in a way that makes failing tests inside the exception block report to the line where exception() is called. Our author disagrees with that whole situation, and thinks the actual line of the failing test is more important. Facts.

Ultimately though? Test::Fatal can't be changed, and people probably already depend on that behavior. So here we are. No drama, just divergence 🌈

---

💜 SOURCE 💜

The source code repository for Test2-Suite can be found at https://github.com/Test-More/test-more/. Go star it or whatever, the link is right there bestie ⭐

---

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

---

And that's the whole page babes 💅 This legend of a doc is sitting at perl v5.44.0, dated 2026-10-17, filed under Test2:...ception(3perl). Obsessed. Go write some exception tests, you got this 🦋💖✨