1Test::Abortable(3)    User Contributed Perl Documentation   Test::Abortable(3)
2
3
4

NAME

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

VERSION

10       version 0.003
11

OVERVIEW

13       Test::Abortable provides a simple system for catching some exceptions
14       and turning them into test events.  For example, consider the code
15       below:
16
17         use Test::More;
18         use Test::Abortable;
19
20         use My::API; # code under test
21
22         my $API = My::API->client;
23
24         subtest "collection distinction" => sub {
25           my $result = $API->do_first_thing;
26
27           is($result->documents->first->title,  "The Best Thing");
28           isnt($result->documents->last->title, "The Best Thing");
29         };
30
31         subtest "document transcendence"   => sub { ... };
32         subtest "semiotic multiplexing"    => sub { ... };
33         subtest "homoiousios type vectors" => sub { ... };
34
35         done_testing;
36
37       In this code, "$result->documents" is a collection.  It has a "first"
38       method that will throw an exception if the collection is empty.  If
39       that happens in our code, our test program will die and most of the
40       other subtests won't run.  We'd rather that we only abort the subtest.
41       We could do that in a bunch of ways, like adding:
42
43         return fail("no documents in response") if $result->documents->is_empty;
44
45       ...but this becomes less practical as the number of places that might
46       throw these kinds of exceptions grows.  To minimize code that boils
47       down to "and then stop unless it makes sense to go on," Test::Abortable
48       provides a means to communicate, via exceptions, that the running
49       subtest should be aborted, possibly with some test output, and that the
50       program should then continue.
51
52       Test::Abortable exports a "subtest" routine that behaves like the one
53       in Test::More but will handle and recover from abortable exceptions
54       (defined below).  It also exports "testeval", which behaves like a
55       block eval that only catches abortable exceptions.
56
57       For an exception to be "abortable," in this sense, it must respond to a
58       "as_test_abort_events" method.  This method must return an arrayref of
59       arrayrefs that describe the Test2 events to emit when the exception is
60       caught.  For example, the exception thrown by our sample code above
61       might have a "as_test_abort_events" method that returns:
62
63         [
64           [ Ok => (pass => 0, name => "->first called on empty collection") ],
65         ]
66
67       It's permissible to have passing Ok events, or only Diag events, or
68       multiple events, or none — although providing none might lead to some
69       serious confusion.
70
71       Right now, any exception that provides this method will be honored.  In
72       the future, a facility for only allowing abortable exceptions of a
73       given class may be added.
74

PERL VERSION

76       This library should run on perls released even a long time ago.  It
77       should work on any version of perl released in the last five years.
78
79       Although it may work on older versions of perl, no guarantee is made
80       that the minimum required version will not be increased.  The version
81       may be increased for any reason, and there is no promise that patches
82       will be accepted to lower the minimum required perl.
83

FUNCTIONS

85   subtest
86         subtest "do some stuff" => sub {
87           do_things;
88           do_stuff;
89           do_actions;
90         };
91
92       This routine looks just like Test::More's "subtest" and acts just like
93       it, too, with one difference: the code item passed in is executed in a
94       block "eval" and any exception thrown is checked for
95       "as_test_abort_events".  If there's no exception, it returns normally.
96       If there's an abortable exception, the events are sent to the test hub
97       and the subtest finishes normally.  If there's a non-abortable
98       exception, it is rethrown.
99
100   testeval
101         my $result = testeval {
102           my $x = get_the_x;
103           my $y = acquire_y;
104           return $x * $y;
105         };
106
107       "testeval" behaves like "eval", but only catches abortable exceptions.
108       If the code passed to "testeval" throws an abortable exception
109       "testeval" will return false and put the exception into $@.  Other
110       exceptions are propagated.
111

EXCEPTION IMPLEMENTATIONS

113       You don't need to use an exception class provided by Test::Abortable to
114       build abortable exceptions.  This is by design.  In fact,
115       Test::Abortable doesn't ship with any abortable exception classes at
116       all.  You should just add a "as_test_abort_events" where it's useful
117       and appropriate.
118
119       Here are two possible simple implementations of trivial abortable
120       exception classes.  First, using plain old vanilla objects:
121
122         package Abort::Test {
123           sub as_test_abort_events ($self) {
124             return [ [ Ok => (pass => 0, name => $self->{message}) ] ];
125           }
126         }
127         sub abort ($message) { die bless { message => $message }, 'Abort::Test' }
128
129       This works, but if those exceptions ever get caught somewhere else,
130       you'll be in a bunch of pain because they've got no stack trace, no
131       stringification behavior, and so on.  For a more robust but still tiny
132       implementation, you might consider failures:
133
134         use failures 'testabort';
135         sub failure::testabort::as_test_abort_events ($self) {
136           return [ [ Ok => (pass => 0, name => $self->msg) ] ];
137         }
138
139       For whatever it's worth, the author's intent is to add
140       "as_test_abort_events" methods to his code through the use of
141       application-specific Moose roles,
142

AUTHOR

144       Ricardo SIGNES <cpan@semiotic.systems>
145

CONTRIBUTOR

147       Ricardo Signes <rjbs@semiotic.systems>
148
150       This software is copyright (c) 2016 by Ricardo SIGNES.
151
152       This is free software; you can redistribute it and/or modify it under
153       the same terms as the Perl 5 programming language system itself.
154
155
156
157perl v5.36.0                      2023-01-20                Test::Abortable(3)
Impressum