.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Async::Test 3pm"
.TH IO::Async::Test 3pm "2014-10-21" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"IO::Async::Test" \- utility functions for use in test scripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Test::More tests => 1;
\& 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, \*(AqThe event happened\*(Aq );
\&
\& ...
\&
\& my $buffer = "";
\& my $handle = IO::Handle\-> ...
\&
\& wait_for_stream { length $buffer >= 10 } $handle => $buffer;
\&
\& is( substr( $buffer, 0, 10, "" ), "0123456789", \*(AqBuffer was correct\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides utility functions that may be useful when writing test
scripts for code which uses \f(CW\*(C`IO::Async\*(C'\fR (as well as being used in the
\&\f(CW\*(C`IO::Async\*(C'\fR test scripts themselves).
.PP
Test scripts are often synchronous by nature; they are a linear sequence of
actions to perform, interspersed with assertions which check for given
conditions. This goes against the very nature of \f(CW\*(C`IO::Async\*(C'\fR which, being an
asynchronisation framework, does not provide a linear stepped way of working.
.PP
In order to write a test, the \f(CW\*(C`wait_for\*(C'\fR function provides a way of
synchronising the code, so that a given condition is known to hold, which
would typically signify that some event has occured, the outcome of which can
now be tested using the usual testing primitives.
.PP
Because the primary purpose of \f(CW\*(C`IO::Async\*(C'\fR is to provide \s-1IO\s0 operations on
filehandles, a great many tests will likely be based around connected pipes or
socket handles. The \f(CW\*(C`wait_for_stream\*(C'\fR function provides a convenient way
to wait for some content to be written through such a connected stream.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "testing_loop( $loop )"
.el .SS "testing_loop( \f(CW$loop\fP )"
.IX Subsection "testing_loop( $loop )"
Set the \f(CW\*(C`IO::Async::Loop\*(C'\fR object which the \f(CW\*(C`wait_for\*(C'\fR function will loop
on.
.ie n .SS "wait_for( $condfunc )"
.el .SS "wait_for( \f(CW$condfunc\fP )"
.IX Subsection "wait_for( $condfunc )"
Repeatedly call the \f(CW\*(C`loop_once\*(C'\fR method on the underlying loop (given to the
\&\f(CW\*(C`testing_loop\*(C'\fR function), until the given condition function callback
returns true.
.PP
To guard against stalled scripts, if the loop indicates a timeout for 10
consequentive seconds, then an error is thrown.
.ie n .SS "wait_for_stream( $condfunc, $handle, $buffer )"
.el .SS "wait_for_stream( \f(CW$condfunc\fP, \f(CW$handle\fP, \f(CW$buffer\fP )"
.IX Subsection "wait_for_stream( $condfunc, $handle, $buffer )"
As \f(CW\*(C`wait_for\*(C'\fR, but will also watch the given \s-1IO\s0 handle for readability, and
whenever it is readable will read bytes in from it into the given buffer. The
buffer is \s-1NOT\s0 initialised when the function is entered, in case data remains
from a previous call.
.PP
\&\f(CW$buffer\fR can also be a \s-1CODE\s0 reference, in which case it will be invoked
being passed data read from the handle, whenever it is readable.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>