1Test::Abortable(3) User Contributed Perl Documentation Test::Abortable(3)
2
6 Test::Abortable - subtests that you can die your way out of ... but
7 survive
8
10 version 0.003
11
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 use Test::More;
18 use Test::Abortable;
19 use My::API; # code under test
21 my $API = My::API->client;
23 subtest "collection distinction" => sub {
25 my $result = $API->do_first_thing;
26 is($result->documents->first->title, "The Best Thing");
28 isnt($result->documents->last->title, "The Best Thing");
29 };
30 subtest "document transcendence" => sub { ... };
32 subtest "semiotic multiplexing" => sub { ... };
33 subtest "homoiousios type vectors" => sub { ... };
34 done_testing;
36 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 return fail("no documents in response") if $result->documents->is_empty;
44 ...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 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 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 [
64 [ Ok => (pass => 0, name => "->first called on empty collection") ],
65 ]
66 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 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
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 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
85 subtest
86 subtest "do some stuff" => sub {
87 do_things;
88 do_stuff;
89 do_actions;
90 };
91 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 testeval
101 my $result = testeval {
102 my $x = get_the_x;
103 my $y = acquire_y;
104 return $x * $y;
105 };
106 "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
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 Here are two possible simple implementations of trivial abortable
120 exception classes. First, using plain old vanilla objects:
121 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 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 use failures 'testabort';
135 sub failure::testabort::as_test_abort_events ($self) {
136 return [ [ Ok => (pass => 0, name => $self->msg) ] ];
137 }
138 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
144 Ricardo SIGNES <cpan@semiotic.systems>
145
147 Ricardo Signes <rjbs@semiotic.systems>
148
150 This software is copyright (c) 2016 by Ricardo SIGNES.
151 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.
154perl v5.38.0 2023-07-21 Test::Abortable(3)