Test::...aitable(3pm)

✨ NAME ✨

Test::Future::AsyncAwait::Awaitable — conformance tests for the awaitable role API 💖

okay so bestie, this is a whole module whose entire job is to vibe-check your class and make sure it actually implements the Future::AsyncAwait::Awaitable role properly. it's giving "quality control but make it cute" 🎀

---

🌸 SYNOPSIS 🌸

use Test::More;
use Test::Future::AsyncAwait::Awaitable;

use My::Future::Subclass;

test_awaitable "My subclass of Future",
   class => "My::Future::Subclass";

done_testing;

like. look at that. one function call and your subclass gets a whole personality test. slay 💅

---

🦋 DESCRIPTION 🦋

This module gives you exactly one test function, and that function runs a whole lil suite of subtests to check that a given class has a useable implementation of the Future::AsyncAwait::Awaitable role.

It runs tests that simulate all the various ways Future::AsyncAwait will try to use an instance of your class, so it can check whether your implementation is actually valid. no cap, it's thorough 🔥

---

👑 FUNCTIONS 👑

💜 test_awaitable

test_awaitable( $title, %args );

Runs the API conformance tests. $title gets printed in the test description output, so it should be some human-friendly string — something your future self can read without crying 😭

It takes these named arguments, bestie:

• class => STRING — gives the name of the class. This is the class on which the AWAIT_NEW_DONE and AWAIT_NEW_FAIL methods will be invoked. so like, the main character of this whole operation 👑
• new => CODE — optional! gives a callback function to invoke to construct a new pending instance; the tests use it to create pending instances that would be passed into the await keyword. And the reason it works like this: this isn't part of the API as such, so the test code does not rely on being able to directly do this via the API. (iykyk)

This argument is optional; if you don't provide it, the tests will simply try to invoke the regular new constructor on the given class name. For most implementations this should be sufficient. fr fr, most of y'all don't even need it 🫶

$f = $new->();

• cancel => CODE — optional. gives a callback function to invoke to cancel a pending instance, if your implementation provides cancellation semantics. If this callback is provided, then an extra subtest suite runs to check the API around cancellation. so if you got cancel vibes, we're gonna test the cancel vibes ✨

$cancel->( $f );

• force => CODE — optional. gives a callback function to invoke to wait for a promise to invoke its on-ready callbacks. Some future-like implementations will run these immediately when the future is marked as done or failed, and so this callback will not be required. Other implementations will defer these invocations — maybe until the next tick of an event loop or something like that. In the latter case, those implementations should provide a way for the test to wait for this to happen.

$force->( $f );

lowkey important: force is the "hey bestie, chill for a sec until the callbacks actually fire" hook. if your implementation defers, you need to hand it over. no callback, no waiting, and the tests will not know what to do with themselves 💀

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk> — periodt, the icon responsible 💖

---

and that's the whole page, bestie! this came to you from the User Contributed Perl Documentation, perl v5.42.3, dated 2026-08-20. go make your awaitable class proud 🧚⭐