NAME Test::MTA::Exim4 - Test Anything interface for testing Exim4 configurations VERSION Version 0.03 SYNOPSIS Test::MTA::Exim4 allows the testing of an `exim' installation and configuration using the perl TAP (Test Anything Protocol) methodology. This allows the writing of some simple test scripts which can check for features of `exim' and check that this configuration routes, accepts or rejects mail as you would expect. As such it is an ideal system for creating a test suite for your mail configuration allowing you to check that there are no unexpected regressions when you make a change. You need to be aware that an `exim' installation depends on more than just a config file - the exim binary, and the installation environment may effect the behaviour and/or routing of messages. You really need to do final configuration tests on the box that the system will be running on in production. WARNING At present this module is experimental - both the API and implementation are subject to change. To this end I welcome discussion on how best to implement or expose functionality. There is other work proposed to produce similar test modules for other MTAs and so a common mechanism or compatibility layer between them is possible - this module has been produced to get something out as code is a better discussion point than vapourware ideas! METHODS new my $exim = Test::MTA::Exim4->new( \%fields ); Create a new exim configuration testing object. You may pass configuration information in as a hash reference - this is the only point at which the locations of the exim binary and configuration file may be set. reset Resets the internal state. Not sure when this might be useful! config_ok Checks that `exim' considers the configuration file as syntactically valid. The config file must be specified when `new' is called, otherwise the default is used. exim_version Returns the version of `exim' seen when the configuration was checked. This is intended for use within your own tests for appropriate versions, for example:- # ensure we are running exim 4.69 or later ok(($exim->exim_version gt '4.69'), 'Exim version check'); exim_build Returns the build number of `exim' seen when the configuration was checked. This is intended for use within your own tests for appropriate versions/builds. has_capability $exim->has_capability($type, $what, $optional_msg) $exim->has_capability('lookup', 'lsearch', 'Has lsearch capability') Checks that `exim' has the appropriate capability. This is taken from the lists of capabilities listed by `exim -bV' The types of capability are:- * support_for * lookup * authenticator * router * transport The items within a capability are processed to be lowercase alphanumeric only - so `iconv' rather than `iconv()' as output by exim. The subitems (for example `maildir' is a subitem of `appendfile') are treated as separately checkable items. has_not_capability Precisely the opposite of has_capability with an opposite test - so fails if this does exist. routes_ok $exim->routes_ok($address, $optional_msg); $exim->routes_ok('address@example.com', 'Checking routing'); Checks that `exim' with this configuration can route to the address given. Accepts any working address which may route to any number of final targets as long as there are no undeliverable addresses in the set. routes_as_ok $exim->routes_as_ok($address, $target, $optional_msg); $exim->routes_as_ok('address@example.com', {transport => 'local_smtp}, 'Checking routing'); Checks that `exim' with this configuration routes to the address given with the appropriate target results. The target is an arrayref of hashes (or as a special case a single hash), which matches against the addresses section of the result from _run_exim_bt. Each address matches if all the elements given in the target hash match (so an empty hash will match anything). See _run_exim_bt for hash elements. discards_ok $exim->discards_ok($address, $optional_msg); $exim->discards_ok('discards@example.com', 'Checking discarding'); Checks that `exim' with this configuration will discard the given address. undeliverable_ok $exim->undeliverable_ok($address, $optional_msg); $exim->undeliverable_ok('discards@example.com', 'Checking discarding'); Checks that `exim' with this configuration will consider the given address to be undeliverable. INTERNAL METHODS These methods are not intended to be run by end users, but are exposed. _run_exim_command Runs an exim instance with the appropriate config file and _run_exim_bv Runs `exim -bV' with the appropriate configuration file, to check that the configuration file is valid. The output of the command is parsed and stashed and used to provide the functions to check versions numbers and capabilities. _run_exim_bt Runs `exim -bt' (address test mode) with the appropriate configuration file, to check how the single address passed routes. The output of the command is parsed and passed back in the results. The results structure is hash that looks like:- { all_ok => # no invocation errors deliverable => # number of deliverable addresses undeliverable => # number of undeliverable addresses total => # total number of addresses addresses => {} } The `addresses' part of the structure has one key for each resultant address, the value of which is another hash, which may contain the following items:- * ok True if the address routed OK, False otherwise. * discarded True if the address was discarded by the router, false or missing if not. * data Scalar of lines picked out of exim output related to this address and not otherwise recognised. * router The router name used to handle this address. * transport The transport name used to handle this address. * address The final destination addresss. * original The original address that was used within this transformation. This is actually an arrayref each containing an address as several transformations may take place. * target For a local transport, the delivery target. _diag Spits out some Test::Builder diagnostics for the last run command. Used internally by some tests on failure. The output data is the last error seen by IPC::Cmd and the complete output of the command. AUTHOR Nigel Metheringham, `' BUGS Please report any bugs or feature requests to `bug-test-mta-exim4 at rt.cpan.org', or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-MTA-Exim4. 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::MTA::Exim4 Warning At this point the module is *not* released to CPAN - still in early development and subject to change in a big way (including renaming, or even just dropping it). However when/if it is released, further information will be found at these locations You can also look for information at: * github - source control system (latest development version will always be here) http://github.com/nigelm/Test-MTA-Exim4/ * RT: CPAN's request tracker http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-MTA-Exim4 * AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/Test-MTA-Exim4 * CPAN Ratings http://cpanratings.perl.org/d/Test-MTA-Exim4 * Search CPAN http://search.cpan.org/dist/Test-MTA-Exim4/ ACKNOWLEDGEMENTS The module draws very strongly on the Test::Exim4::Routing module by Max Maischein. It is structured differently, and is currently very experimental (meaning the API may change in a big way), so these changes were made as a new module in a name space that is intended for use by similar modules for other MTAs. COPYRIGHT & LICENSE Copyright 2009-2010 Nigel Metheringham. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.