Test::Abortable(3pm)

🦋 Test::Abortable — the perl module, bestie ✨

okay so this is Test::Abortable, straight out of the User Contributed Perl Documentation section (that's the 3pm part, iykyk 💅). It's the module that lets your subtests die dramatically and then, like, get back up. resilient queen behavior honestly 👑

---

✨ NAME ✨

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

---

🌸 VERSION 🌸

version 0.003 — she's tiny, she's iconic

---

🎀 OVERVIEW 🎀

So Test::Abortable gives you a whole little system for catching some exceptions and turning them into test events. Not all of them. Some. We'll get to that, bestie, don't rush me 😭

Like, look at this code:

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;

Okay so in this code, $result->documents is a collection. And it's got this first method that will straight up throw an exception if the collection is empty 💀

And the way that wrecks us? If that happens, our whole test program dies. Not just one subtest — the program. All the other subtests never even get to run. they never got their moment 😭

We would much rather just abort the one subtest. Like, respectfully, only that one.

And yeah, we could do it a bunch of ways, for example by adding:

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

…but that gets less and less practical the more places there are that might throw these kinds of exceptions. The list grows. The vibe declines. Not cute.

So to minimize code that basically boils down to "and then stop unless it makes sense to go on," Test::Abortable gives you a way to communicate — via exceptions — that the running subtest should be aborted, possibly with some test output attached, and that the program should then just... keep going. main character energy, the show continues 🌈

Here's what it actually gives you:

• Test::Abortable exports a subtest routine that behaves like the one in Test::More, except it will handle and recover from abortable exceptions (defined in a sec, bestie, patience).
• It also exports testeval, which behaves like a block eval that only catches abortable exceptions.

now. for an exception to be "abortable" in this sense, it has to respond to a as_test_abort_events method. That's the whole vibe check. 👑

This method must return an arrayref of arrayrefs that describe the Test2 events to emit when the exception gets caught. So like, the exception thrown by our sample code up there might have a as_test_abort_events method that returns:

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

and it's totally permissible to have:

• passing Ok events ✅
• or only Diag events 📝
• or multiple events 📚
• or none 🫥 — though ngl, 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. so, like, watch this space ✨

---

🧚 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. grandma perl friendly, we love to see it 🫶

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.

so basically: don't come for her about the floor, she reserves the right to raise it 💅

---

💖 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, bestie:

the code item passed in is executed in a block eval, and any exception thrown is checked for as_test_abort_events.

And then it's a whole little branching situation:

• If there's no exception, it returns normally. all good, no notes ✨
• If there's an abortable exception, the events are sent to the test hub and the subtest finishes normally. she survives!! 🦋
• If there's a non-abortable exception, it is rethrown. we are not catching that one, that's above our pay grade 💀

⭐ testeval

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

testeval behaves like eval, but it only catches abortable exceptions.

So if the code you pass to testeval throws an abortable exception, testeval will return false and put the exception into $@. And other exceptions? Those are propagated. not our problem, they keep moving 🚶‍♀️

---

👑 EXCEPTION IMPLEMENTATIONS 👑

okay crucial info: you do not 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. zero. none. it's giving minimalist ✨

You should just add a as_test_abort_events where it's useful and appropriate. that's it. that's the whole ask.

Here are two possible simple implementations of trivial abortable exception classes:

number one — 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. lowkey tragic. they're naked exceptions. 🙈

number two — 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. that's the dream, that's the plan 🎀

---

🌈 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.

---

and that's the whole page bestie, no cap 🫶 it's Test::Abortable version 0.003, and it ships as perl v5.40.1 dated 2025-05-04 — go forth and let your subtests survive their little meltdowns 💖✨