The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Mail-0.06
River stage zero No dependents
1 ++
/ Test::Mail

NAME

Test::Mail - Test framework for email applications

VERSION

Version 0.06

SYNOPSIS

    use Test::Mail
    my $tm = Test::Mail->new( logfile => $logfile );
    $tm->accept();
    sub first_test { }
    sub second_test { }
    ...

DESCRIPTION

Test::Mail provides a framework for testing applications which send and receive email.

A typical example of an email application might send a notification to a certain email address, setting certain headers in certain ways and having certain content in the body of the email. It would be nice to be able to test these things automatically, however most email applications are currently tested by visual inspection of the email received.

Test::Mail allows you to automate the testing of email applications by piping any relevant email through a Test::Mail script.

"Relevant" email is identified by the presence of an X-Test-Mail: header. You should set this email in your application or whatever you use to generate the mail.

    X-Test-Mail: birthday_notification

The value of that header is the name of a subroutine which exists in your Test::Mail script. The subroutine contains Test::More tests to run on the email:

    sub birthday_notification {
        is($header->get("From:"), 'birthdays@example.com', "From address check");
        like($body, qr/Today's Birthdays/, "Email body check");
    }

This allows you to have tests for multiple different kinds of email in one script.

Note that $header and $body are set by Test::Mail for your convenience. $header is a Mail::Header object. $body is the body of the email as a single string. MIME attachments etc are not supported (yet).

The results of the tests run are output to the logfile you specify, and look something like this:

    # test results for birthday_notification for <msgid1234@example.com>
    ok 1 - From address check
    ok 2 - Email body check

    # test results for support_request for <msgid5678@example.com>
    ok 1 - To address check
    not ok 2 - Subject line
    not ok 3 - Included ticket number
    ok 4 - Body contains plain text

Note that while these are roughly similar to normal CPAN test output conventions, counting only occurs on a per-email basis

Sending incoming mail to Test::Mail

To call Test::Mail, simply put a suitable filter in your .procmailrc, Mail::Audit script, or whatever you use to filter your email. Here's how I'd do it with Mail::Audit:

    if ($mail->{obj}->head->get("X-Test-Mail")) {
        $mail->pipe("testmail.pl");
    }

If for some reason you want to test mail that doesn't already have an X-Test-Mail: header, you could do something like:

    if ($mail->{subject} =~ /test/i) {
        $mail->{obj}->head->add("X-Test-Mail", "subject_auto");
        $mail->pipe("testmail.pl");
    }

Unaddressed issues

The above is a rough outline of version 1. There are several issues I don't yet know how to deal with, which I'm listing here just in case anyone has any good ideas:

  • Sending output somewhere more useful than a logfile

  • Integrating into a real "test suite" that's friendly to Test::Harness

  • Handling MIME in a suitable way

METHODS

new()

Constructor method. Takes a hash of arguments. The only current argument is "logfile" which is the file to which test logs will be sent.

accept()

Accept a single email and test it. Doesn't take any args.

This will run the email through whatever subroutine is described in the "X-Test-Mail" header.

header()

Convenience accessor method for the header of the email. Returns a Mail::Header object.

body()

Convenience accessor method for the body of the email. Returns a plain text string.

AUTHOR

Kirrily Robert, <skud at cpan.org>

BUGS

Please report any bugs or feature requests to bug-test-mail at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Mail. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Test::Mail

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2007 Kirrily Robert, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.