Test::...Future(3pm)

👑 NAME 👑

Test::ExpectAndCheck::Future (the header calls it Test::...Future(3pm), and it lives in the User Contributed Perl Documentation corner of your system) — this is "expect/check"-style unit testing, but for methods that return a Future. Like, mocking but make it async. 💅

---

✨ SYNOPSIS ✨

Ok bestie, here's the whole vibe in one go:

use Test::More;
use Test::ExpectAndCheck::Future;

use Future::AsyncAwait;

my ( $controller, $mock ) = Test::ExpectAndCheck::Future->create;

{
   $controller->expect( act => 123, 45 )
      ->will_done( 678 );

   is( await $mock->act( 123, 45 ), 678, '$mock->act yields result' );

   $controller->check_and_clear( '->act' );
}

done_testing;

---

🦋 DESCRIPTION 🦋

So this package makes objects that help you write unit tests with mocked object instances. Each mocked instance expects to receive a given list of method calls, fr. Every one of those method calls gets checked that it got the right arguments, and then it returns a Future instance that'll yield the result you prescribed. And at the end of each test, each object gets checked to make sure all the expected methods actually got called. No cap. 🙈

It's a variation of Test::ExpectAndCheck, but with extra assistance around the results of the invoked methods. Every invoked method returns a Future instance, and then will_done or will_fail can set the desired eventual result of that future instance for each expectation. Iconic.

These returned instances are implemented using Test::Future::Deferred, so heads up: they are not immediately ready. Nope. They only become ready after a toplevel await expression or a call to the get method. The whole point is that unit tests run similarly to real-world behaviour, where most futures handed back by real-world interfaces (think IO systems 👀) aren't immediately ready either. If you want that behaviour switched off for individual expectations, use the immediately method. Easy. Periodt. ⭐

---

🎀 EXPECTATIONS 🎀

will_done

$exp->will_done( @result );

Since version 0.04.

Sets that this method call will return a Future instance which succeeds with the given result. Slay. ✅

will_fail

$exp->will_fail( $message, $category, @more );

Since version 0.04.

Sets that this method call will return a Future instance which fails with the given message, plus optionally a category name and extra details. It's giving drama but on purpose. 💀

immediately

$exp->will_done( ... )->immediately;

$exp->will_fail( ... )->immediately;

Since version 0.02.

Switches this expectation over to returning an immediate future, instead of a deferred one. Main character energy, no waiting around. ⚡

remains_pending

$exp->remains_pending;

Since version 0.03.

Sets that the future returned by this method just... never completes, and simply remains pending. Forever. Lowkey haunting but it's a test fixture so it's fine. 🫶

will_also_later

$exp->will_also_later( sub { ... } );

Since version 0.04.

Adds extra code that'll run when the expected method is called — after the returned future has completed, okurrr. This happens by the use of Test::Future::Deferred.

When it gets invoked, the code body runs in void context with no additional arguments.

---

🌸 AUTHOR 🌸

Paul Evans <leonerd@leonerd.org.uk> — ty for your service king 👑

---

And that's the whole page bestie!! 🎀 This little beauty is perl v5.40.1, dated 2026-01-02, and it lives under User Contributed Perl Documentation as Test::...Future(3pm). Go forth and mock responsibly. Mwah 💋 🦋✨