1IO::Async::Test(3pm)  User Contributed Perl Documentation IO::Async::Test(3pm)
2
3
4

NAME

6       "IO::Async::Test" - utility functions for use in test scripts
7

SYNOPSIS

9          use Test::More tests => 1;
10          use IO::Async::Test;
11
12          use IO::Async::Loop;
13          my $loop = IO::Async::Loop->new;
14          testing_loop( $loop );
15
16          my $result;
17
18          $loop->do_something(
19             some => args,
20
21             on_done => sub {
22                $result = the_outcome;
23             }
24          );
25
26          wait_for { defined $result };
27
28          is( $result, what_we_expected, 'The event happened' );
29
30          ...
31
32          my $buffer = "";
33          my $handle = IO::Handle-> ...
34
35          wait_for_stream { length $buffer >= 10 } $handle => $buffer;
36
37          is( substr( $buffer, 0, 10, "" ), "0123456789", 'Buffer was correct' );
38
39          my $result = wait_for_future( $stream->read_until( "\n" ) )->get;
40

DESCRIPTION

42       This module provides utility functions that may be useful when writing
43       test scripts for code which uses IO::Async (as well as being used in
44       the IO::Async test scripts themselves).
45
46       Test scripts are often synchronous by nature; they are a linear
47       sequence of actions to perform, interspersed with assertions which
48       check for given conditions. This goes against the very nature of
49       IO::Async which, being an asynchronisation framework, does not provide
50       a linear stepped way of working.
51
52       In order to write a test, the "wait_for" function provides a way of
53       synchronising the code, so that a given condition is known to hold,
54       which would typically signify that some event has occurred, the outcome
55       of which can now be tested using the usual testing primitives.
56
57       Because the primary purpose of IO::Async is to provide IO operations on
58       filehandles, a great many tests will likely be based around connected
59       pipes or socket handles. The "wait_for_stream" function provides a
60       convenient way to wait for some content to be written through such a
61       connected stream.
62

FUNCTIONS

64   testing_loop
65          testing_loop( $loop )
66
67       Set the IO::Async::Loop object which the "wait_for" function will loop
68       on.
69
70   wait_for
71          wait_for { COND } OPTS
72
73       Repeatedly call the "loop_once" method on the underlying loop (given to
74       the "testing_loop" function), until the given condition function
75       callback returns true.
76
77       To guard against stalled scripts, if the loop indicates a timeout for
78       (a default of) 10 consequentive seconds, then an error is thrown.
79
80       Takes the following named options:
81
82       timeout => NUM
83           The time in seconds to wait before giving up the test as being
84           stalled.  Defaults to 10 seconds.
85
86   wait_for_stream
87          wait_for_stream { COND } $handle, $buffer
88
89       As "wait_for", but will also watch the given IO handle for readability,
90       and whenever it is readable will read bytes in from it into the given
91       buffer. The buffer is NOT initialised when the function is entered, in
92       case data remains from a previous call.
93
94       $buffer can also be a CODE reference, in which case it will be invoked
95       being passed data read from the handle, whenever it is readable.
96
97   wait_for_future
98          $future = wait_for_future $future
99
100       Since version 0.68.
101
102       A handy wrapper around using "wait_for" to wait for a Future to become
103       ready. The future instance itself is returned, allowing neater code.
104

AUTHOR

106       Paul Evans <leonerd@leonerd.org.uk>
107
108
109
110perl v5.36.1                      2023-05-14              IO::Async::Test(3pm)