NAME

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

VERSION

version 0.002

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.

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 <rjbs@cpan.org>

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.

cpanm Test::Abortable

perl -MCPAN -e shell
install Test::Abortable