---
name: "Test2::Tools::Exception"
section: "3p"
platform: "openbsd"
package: "man"
version: "8.0-current-20261101"
release: "OpenBSD 8.0-current (2026-11-01)"
platforms: ["openbsd"]
url: "https://new.carta.tech/Test2::Tools::Exception"
---

# Test2::Tools::Exception(3p)

Test2 based tools for checking exceptions

## NAME

Test2::Tools::Exception - Test2 based tools for checking exceptions

## DESCRIPTION

This is the Test2 implementation of code used to test exceptions. This is similar to Test::Fatal, but it intentionally does much less.

## SYNOPSIS

```
    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 will trap any exception the codeblock throws. If no exception is thrown the sub will return undef. If an exception is thrown it will be returned. This function preserves `$@`, it will not be altered from its value before the sub is called.

- $bool = lives { ... }

  This will trap any exception thrown in the codeblock. It will return 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 that you can look at it.

- $bool = try\_ok { ... }

  - $bool = try\_ok { ... } "Test Description"

  This will run 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, this is by design so that you can obtain the exception if desired.

## 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. I disagree with this, and think the actual line of the failing test is more important. Ultimately, though Test::Fatal cannot be changed, people probably already depend on that behavior.

## 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/*