Test2::Tools::Exception(3)                 User Contributed Perl Documentation


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/Test2-Suite/.

MAINTAINERS
       Chad Granum <exodist@cpan.org>

AUTHORS
       Chad Granum <exodist@cpan.org>

COPYRIGHT
       Copyright 2018 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/

perl v5.38.2                      2024-05-12        Test2::Tools::Exception(3)