IO::Async::Test(3pm)

💖 IO::Async::Test(3pm) — bestie edition 💖

okay so this is a page from the User Contributed Perl Documentation, and it's literally called IO::Async::Test — utility functions for use in test scripts. yes babe, testing tools. we love a supportive module. 🫶

✨ NAME ✨

IO::Async::Test — utility functions for use in test scripts. that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

like, here's the whole thing in action, no cap:

use Test2::V0;
use Future::AsyncAwait;
use IO::Async::Test;

use IO::Async::Loop;
my $loop = IO::Async::Loop->new;
testing_loop( $loop );

my $result;

$loop->do_something(
   some => args,

   on_done => sub {
      $result = the_outcome;
   }
);

wait_for { defined $result };

is( $result, what_we_expected, 'The event happened' );

...

my $buffer = "";
my $handle = IO::Handle-> ...

wait_for_stream { length $buffer >= 10 } $handle => $buffer;

is( substr( $buffer, 0, 10, "" ), "0123456789", 'Buffer was correct' );

my $result = await wait_for_future( $stream->read_until( "\n" ) );

done_testing;

periodt. that's the whole flow. ✨

🦋 DESCRIPTION 🦋

so this module hands you utility functions that are useful when you're writing test scripts for code that uses IO::Async — and btw, it's also used in the IO::Async test scripts themselves. icon behaviour. 🎀

here's the tea, bestie: test scripts are often synchronous by nature. they're just a linear sequence of actions to perform, with assertions sprinkled in between checking for given conditions. and that lowkey clashes with the very nature of IO::Async, because IO::Async is an asynchronisation framework and it just does not give you a linear stepped way of working. no linear steps for you. 🙈

so, in order to write a test, the wait_for function gives you a way of synchronising the code — so that a given condition is known to hold. which typically means: some event happened, and now you can test the outcome using the usual testing primitives. slay.

and because the primary purpose of IO::Async is to provide IO operations on filehandles, a whole lot of tests are gonna be based around connected pipes or socket handles. so the wait_for_stream function is there to give you a convenient way to wait for some content to be written through such a connected stream. it's giving convenience. 💅

---

🔥 FUNCTIONS 🔥

🎀 testing_loop 🎀

testing_loop( $loop );

this sets the IO::Async::Loop object that the wait_for function is gonna loop on. that's it, that's the job. 👑

💜 wait_for 💜

wait_for { COND } OPTS;

it repeatedly calls the loop_once method on the underlying loop (the one you gave to the testing_loop function) until the given condition function callback returns true. over and over and over until the vibe is right. ⭐

bestie, real talk: to guard against stalled scripts, if the loop indicates a timeout for (a default of) 10 consecutive seconds, then an error is thrown. so don't be out here waiting forever. 😭

Takes the following named options:

• timeout => NUM — the time in seconds to wait before giving up the test as being stalled. Defaults to 10 seconds. 💖

🧚 wait_for_stream 🧚

wait_for_stream { COND } $handle, $buffer;

it's like wait_for, but it will also watch the given IO handle for readability, and whenever it's readable it'll read bytes in from it into the given buffer. 📖

careful babes: the buffer is NOT initialised when the function is entered — in case data remains from a previous call. so like, whatever was in there is still in there. 🙈

$buffer can also be a CODE reference — in which case it gets invoked, being passed data read from the handle, whenever it's readable. yes, a coderef as your buffer, we're flexible like that. 💅

🌈 wait_for_future 🌈

$future = wait_for_future $future;

Since version 0.68.

this is a handy wrapper around using wait_for to wait for a Future to become ready. and the future instance itself is returned, which lets you write neater code. it's giving neat. ✨

---

👑 AUTHOR 👑

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

---

okay that's the whole page bestie, go forth and test your async code like the main character you are. no notes. 🌸🦋✨

sign-off time: this was perl v5.40.1, dated 2026-02-21, and the page you just read is IO::Async::Test(3pm). mwah. 💅💖