Test::POP3(3pm)

💌 Test::POP3 — the perl doc you're literally about to read

okay bestie, so this is Test::POP3(3pm), from the User Contributed Perl Documentation crew 🫶 — it's the module that lets you automate email delivery tests, and honestly? it ate. Let's get into it 💅

---

✨ NAME ✨

Test::POP3 — Automate Email Delivery Tests 💖

---

🌸 SYNOPSIS 🌸

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();

---

🦋 DESCRIPTION 🦋

🚨 PLS READ 🚨 this is ALPHA CODE. like, alpha. so the interface is lowkey likely to change, no cap. don't come for me when it shifts. 😭

This module helps you build automated tests for email that gets delivered to a POP3 account. it's giving "set it and forget it" but for inboxes 💖

Messages you pull from the server but that haven't been matched by a test yet get cached — they sit there until either (a) that message is the first one to pass a test, or (b) it gets returned by $pop3->get_email(). And the messages that come back? They're Test::Email objects, periodt. ✨

---

👑 METHODS 👑

• my $pop = Test::POP3->new($href); The arguments you pass in the href are host, user, and pass. that's the whole vibe check 🫶
• my $count = $pop->wait_for_email_count($count, $timeout_seconds?); Calling this method will result in all messages being deleted from the server. 😳 (yes, fr fr.) It'll wait up to $timeout seconds for there to be $count unprocessed messages found on the server. Once $count or more messages show up — or once $timeout seconds have passed — the current email count gets returned. And $timeout_seconds defaults to 30 ⏱️
• my @email = $pop->get_email(); Grab all the email messages currently chilling in the local cache. If you think there might still be messages on the server waiting to be retrieved, you should call $pop3->wait_for_email_count($count) before this method. Heads up: calling this method causes the local cache to be emptied 💀. The email messages you get back are Test::Email objects.
• my $count = $pop->get_email_count($check_server); Returns the number of email messages in the cache. If $check_server is true, the server gets checked once before the count is determined. And if you wanna wait for messages to arrive on the server and then get downloaded before counting? Use $pop3->wait_for_email_count() instead 🌈
• my $ok = $pop->ok($test_href, $description); Calling this method tests the email in the local cache according to whatever's inside $test_href. The first email that passes all the tests gets deleted from the local cache. Since this method only checks the local cache, you're gonna wanna call $pop3->wait_for_email_count() before it. And ok produces TAP output — identical to Test::Simple::ok and Test::More::ok ⭐
• my $parser = $pop->get_parser(); Test::POP3 uses MIME::Parser to process the messages. (MIME is not yet handled by Test::Email — it will be soon, bestie, stay tuned 👀.) Use this method if you want to manage the parser yourself.

---

🎀 EXPORT 🎀

None.

like... nothing. zero. empty. the void. 🙈

---

💜 SEE ALSO 💜

Test::Builder, Test::Simple, Test::More, MIME::Parser

go read those too, iykyk 📚

---

💅 AUTHOR 💅

James Tolley, <james@cpan.org>

---

🌟 COPYRIGHT AND LICENSE 🌟

Copyright (C) 2007 by James Tolley

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.

---

and that's the whole page, babe 🥰 this was perl v5.34.0, dated 2022-06-17, and it's still Test::POP3(3pm) — slay, go write some tests, you got this 👑💖✨