<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Tools/Exception.md. Do not edit. -->

```{index} single: Test2::Tools::Exception
```

# Test2::Tools::Exception

Test2 based tools for checking exceptions

## DESCRIPTION

This is the [Test2](../../Test2.md) implementation of code used to test exceptions. This is
similar to [Test::Fatal](https://metacpan.org/pod/Test::Fatal), but it intentionally does much less.

## SYNOPSIS

```perl
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](https://metacpan.org/pod/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](https://metacpan.org/pod/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/`