NAME
    Test::MTA::Exim4 - Test Anything interface for testing Exim4
    configurations

VERSION
    Version 0.02

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, `<nigelm at cpan.org>'

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.

