.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Test::POP3 3pm"
.TH Test::POP3 3pm "2015-12-25" "perl v5.22.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"
Test::POP3 \- Automate Email Delivery Tests
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Test::POP3;
\&
\&  my $pop = Test::POP3\->new({
\&      host => $host,
\&      user => $user,
\&      pass => $pass,
\&  });
\&  
\&  # this will delete all messages from the server
\&  ok($count == $pop\->wait_for_email_count($count,$timeout),"got $count");
\&
\&  # find and delete a single email message which matches these rules
\&  # see Test::Email for more information
\&  $pop\->ok({
\&    # optional search parameters
\&    to         => ($is or qr/is like/),
\&    from       => ($is or qr/is like/),
\&    subject    => ($is or qr/is like/),
\&    body       => ($is or qr/is like/),
\&    headername => ($is or qr/is like/),
\&  }, "got message");
\&
\&  ok($pop\->get_email_count() == $count, "$count emails in cache");
\&
\&  # get the Test::Email object
\&  my @email = $pop\->get_email();
\&
\&  ok($pop\->delete_all() == 2, "deleted 2 messages");
\&
\&  # tweak MIME::Parser settings
\&  my $parser = $pop\->get_parser();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Please note that this is \s-1ALPHA CODE.\s0 As such, the interface is likely to
change.
.PP
This module can help you to create automated tests of email 
delivered to a \s-1POP3\s0 account.
.PP
Messages retrieved from the server but not yet matched by a test will
be cached until either that message is the first to pass a test, or is
returned by \f(CW\*(C`$pop3\->get_email()\*(C'\fR. Messages returned are Test::Email
objects.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP """my $pop = Test::POP3\->new($href);""" 4
.el .IP "\f(CWmy $pop = Test::POP3\->new($href);\fR" 4
.IX Item "my $pop = Test::POP3->new($href);"
The arguments passed in the href are host, user, and pass.
.ie n .IP """my $count = $pop\->wait_for_email_count($count, $timeout_seconds?);""" 4
.el .IP "\f(CWmy $count = $pop\->wait_for_email_count($count, $timeout_seconds?);\fR" 4
.IX Item "my $count = $pop->wait_for_email_count($count, $timeout_seconds?);"
\&\fBCalling this method will result in all messages being deleted from the server.\fR
This will wait up to \f(CW$timeout\fR seconds for there to be \f(CW$count\fR unprocessed
messages found on the server. After \f(CW$count\fR or more messages are found,
or after \f(CW$timeout\fR seconds, the current email count will be returned. \f(CW$timeout_seconds\fR
defaults to 30.
.ie n .IP """my @email = $pop\->get_email();""" 4
.el .IP "\f(CWmy @email = $pop\->get_email();\fR" 4
.IX Item "my @email = $pop->get_email();"
Get all of the email messages currently in local cache. You should call
\&\f(CW\*(C`$pop3\->wait_for_email_count($count)\*(C'\fR before calling this method if
you think that there may be messages on the server yet to be retrieved.
Calling this method will cause the local cache to be emptied. Email messages
returned will be Test::Email objects.
.ie n .IP """my $count = $pop\->get_email_count($check_server);""" 4
.el .IP "\f(CWmy $count = $pop\->get_email_count($check_server);\fR" 4
.IX Item "my $count = $pop->get_email_count($check_server);"
This will return the number of email messages in the cache. If \f(CW$check_server\fR
is true, then the server will be checked once before the count is determined.
If you would like to wait for messages to arrive on the server, and then be
downloaded prior to counting, use \f(CW\*(C`$pop3\->wait_for_email_count()\*(C'\fR.
.ie n .IP """my $ok = $pop\->ok($test_href, $description);""" 4
.el .IP "\f(CWmy $ok = $pop\->ok($test_href, $description);\fR" 4
.IX Item "my $ok = $pop->ok($test_href, $description);"
Calling this method will cause the email in the local cache to be tested,
according to the contents of \f(CW$test_href\fR. The first email which passes
all tests will be deleted from the local cache. Since this method only checks
the local cache, you will want to call \f(CW\*(C`$pop3\->wait_for_email_count()\*(C'\fR
before calling this method. \f(CW\*(C`ok\*(C'\fR will produce \s-1TAP\s0 output, identical to
\&\f(CW\*(C`Test::Simple::ok\*(C'\fR and \f(CW\*(C`Test::More::ok\*(C'\fR.
.ie n .IP """my $parser = $pop\->get_parser();""" 4
.el .IP "\f(CWmy $parser = $pop\->get_parser();\fR" 4
.IX Item "my $parser = $pop->get_parser();"
Test::POP3 uses MIME::Parser to process the messages. (\s-1MIME\s0 is not yet
handled by \f(CW\*(C`Test::Email\*(C'\fR, it will be soon.) Use this method if you want to
manage the parser.
.SH "EXPORT"
.IX Header "EXPORT"
None.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::Builder, Test::Simple, Test::More, MIME::Parser
.SH "AUTHOR"
.IX Header "AUTHOR"
James Tolley, <james@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by James Tolley
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.