NAME

       Test::Abortable - subtests that you can die your way out of ... but survive

VERSION

       version 0.003

OVERVIEW

       Test::Abortable provides a simple system for catching some exceptions and turning them into test events.
       For example, consider the code below:

         use Test::More;
         use Test::Abortable;

         use My::API; # code under test

         my $API = My::API->client;

         subtest "collection distinction" => sub {
           my $result = $API->do_first_thing;

           is($result->documents->first->title,  "The Best Thing");
           isnt($result->documents->last->title, "The Best Thing");
         };

         subtest "document transcendence"   => sub { ... };
         subtest "semiotic multiplexing"    => sub { ... };
         subtest "homoiousios type vectors" => sub { ... };

         done_testing;

       In this code, "$result->documents" is a collection.  It has a "first" method that will throw an exception
       if the collection is empty.  If that happens in our code, our test program will die and most of the other
       subtests won't run.  We'd rather that we only abort the subtest.  We could do that in a bunch of ways,
       like adding:

         return fail("no documents in response") if $result->documents->is_empty;

       ...but this becomes less practical as the number of places that might throw these kinds of exceptions
       grows.  To minimize code that boils down to "and then stop unless it makes sense to go on,"
       Test::Abortable provides a means to communicate, via exceptions, that the running subtest should be
       aborted, possibly with some test output, and that the program should then continue.

       Test::Abortable exports a "subtest" routine that behaves like the one in Test::More but will handle and
       recover from abortable exceptions (defined below).  It also exports "testeval", which behaves like a
       block eval that only catches abortable exceptions.

       For an exception to be "abortable," in this sense, it must respond to a "as_test_abort_events" method.
       This method must return an arrayref of arrayrefs that describe the Test2 events to emit when the
       exception is caught.  For example, the exception thrown by our sample code above might have a
       "as_test_abort_events" method that returns:

         [
           [ Ok => (pass => 0, name => "->first called on empty collection") ],
         ]

       It's permissible to have passing Ok events, or only Diag events, or multiple events, or none — although
       providing none might lead to some serious confusion.

       Right now, any exception that provides this method will be honored.  In the future, a facility for only
       allowing abortable exceptions of a given class may be added.

PERL VERSION

       This library should run on perls released even a long time ago.  It should work on any version of perl
       released in the last five years.

       Although it may work on older versions of perl, no guarantee is made that the minimum required version
       will not be increased.  The version may be increased for any reason, and there is no promise that patches
       will be accepted to lower the minimum required perl.

FUNCTIONS

   subtest
         subtest "do some stuff" => sub {
           do_things;
           do_stuff;
           do_actions;
         };

       This routine looks just like Test::More's "subtest" and acts just like it, too, with one difference: the
       code item passed in is executed in a block "eval" and any exception thrown is checked for
       "as_test_abort_events".  If there's no exception, it returns normally.  If there's an abortable
       exception, the events are sent to the test hub and the subtest finishes normally.  If there's a non-
       abortable exception, it is rethrown.

   testeval
         my $result = testeval {
           my $x = get_the_x;
           my $y = acquire_y;
           return $x * $y;
         };

       "testeval" behaves like "eval", but only catches abortable exceptions.  If the code passed to "testeval"
       throws an abortable exception "testeval" will return false and put the exception into $@.  Other
       exceptions are propagated.

EXCEPTION IMPLEMENTATIONS

       You don't need to use an exception class provided by Test::Abortable to build abortable exceptions.  This
       is by design.  In fact, Test::Abortable doesn't ship with any abortable exception classes at all.  You
       should just add a "as_test_abort_events" where it's useful and appropriate.

       Here are two possible simple implementations of trivial abortable exception classes.  First, using plain
       old vanilla objects:

         package Abort::Test {
           sub as_test_abort_events ($self) {
             return [ [ Ok => (pass => 0, name => $self->{message}) ] ];
           }
         }
         sub abort ($message) { die bless { message => $message }, 'Abort::Test' }

       This works, but if those exceptions ever get caught somewhere else, you'll be in a bunch of pain because
       they've got no stack trace, no stringification behavior, and so on.  For a more robust but still tiny
       implementation, you might consider failures:

         use failures 'testabort';
         sub failure::testabort::as_test_abort_events ($self) {
           return [ [ Ok => (pass => 0, name => $self->msg) ] ];
         }

       For whatever it's worth, the author's intent is to add "as_test_abort_events" methods to his code through
       the use of application-specific Moose roles,

AUTHOR

       Ricardo SIGNES <cpan@semiotic.systems>

CONTRIBUTOR

       Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2016 by Ricardo SIGNES.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
       programming language system itself.