Test::Future(3pm)

✨ NAME ✨

Test::Future — unit test assertions for Future instances 💖

okay bestie, this is the perl manpage for Test::Future (3pm) and it's literally the glow-up your async test suite has been waiting for 🫶

---

🌸 SYNOPSIS 🌸

use Test::More tests => 2;
use Test::Future;

no_pending_futures {
   my $f = some_function();

   is( $f->get, "result", 'Result of the some_function()' );
} 'some_function() leaves no pending Futures';

like. look at that. so clean. so iconic. 💅

---

🦋 DESCRIPTION 🦋

So this module hands you unit testing assertions that are genuinely useful when you're testing code that's built on — or just vibing with — Future instances or subclasses. That's it, that's the vibe check. ✨

---

💜 FUNCTIONS 💜

no_pending_futures

no_pending_futures( \&code, $name );

Since version 0.29. (so if you're on anything older, this function simply does not exist yet, no cap 😭)

Here's the tea: it runs the block of code you gave it, and while that's happening it keeps track of every single Future instance constructed. Every one. It's watching. 👀

Once your code returns, each of those instances gets inspected to make sure they're not still pending. If they're all either ready (meaning success or failure, both count) or cancelled, the test passes. If even one of them is still pending? The test fails. periodt. 🔥

Now, if Devel::MAT is installed, it gets pulled in to write a memory state dump after a failure happens. It creates a .pmat file named the same as the unit test — except the trailing .t suffix gets replaced with -TEST.pmat, where TEST is the number of the test that failed (just in case there was more than one, which. yeah. been there 🙈). A list of addresses of the Future instances that are still pending also gets printed, to help you debug the whole situation.

Also super important bestie: it is not an error if your code doesn't construct any Future instances at all. Zero futures? Totally fine. And your block of code can contain other testing assertions too — those will all be run before the assertion made by no_pending_futures itself. 🎀

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> 💖

---

that's the whole page, bestie — perl v5.40.1, dated 2025-09-22, straight from the Test::Future(3pm) page itself. go forth and let no future hang around pending, you got this 🌈⭐🦋