NAME
    Test::XT - Generate best practice author tests

SYNOPSIS
      use Test::XT qw(WriteXT);
      
  # Write some specific tests:
      WriteXT(
          'Test::Pod'            => 't/pod.t',
          'Test::CPAN::Meta'     => 't/meta.t',
          'Test::MinimumVersion' => 't/minimumversion.t',
          'Test::Perl::Critic'   => 't/critic.t',
      );

DESCRIPTION
    A number of Test modules have been written over the years to support
    authors. Typically, these modules have standard short test scripts
    documented in them that you can cut and paste into your distribution.

    Unfortunately almost all of these cut-and-paste test scripts are wrong.

    Either the test script runs during install time, or it runs with an
    out-of-date version of the test module, or the author adds the test
    modules as an (unnecesary) dependency at install time, or for automated
    testing.

    Test::XT is a module intended for use in code generators, release
    automation and other ancillary systems. It generates an appropriate test
    script for various testing modules that runs in the appropriate mode for
    each type of execution environment.

    1. End User Install

    At installation time, test scripts should never ever run, even if the
    test modules are installed and available.

    2. Automated Testing

      # Enable automated testing
      $ENV{AUTOMATED_TESTING} = 1

    During automated testing we should run the tests, but only if the
    testing module are already installed and at the current/latest version.

    However, we should not install dependencies during automated testing,
    because failing to install a testing dependency means less runs on your
    code when the entire point of the author tests is to improve the
    standard of testing, not reduce it.

    3. Release/Author Testing

      # Enable author tests
      $ENV{RELEASE_TESTING} = 1;

    All tests should run at release time by the author. Despite this, the
    dependencies STILL should not be checked for in your Makefile.PL or
    Build.PL, because you could end up accidentally having these extra
    dependencies bleed through into your published META.yml.

    This would cause inaccuracies in tools that track dependencies across
    the entire repository via the META.yml files.

SUPPORTED TEST MODULES
    *   Test::Pod

    *   Test::CPAN::Meta

    *   Test::HasVersion

    *   Test::MinimumVersion

    *   Test::Perl::Critic

    *   Test::DistManifest

    *   Test::CheckChanges

    *   Test::Fixme

    *   Test::Pod::Coverage

EXPORTABLE FUNCTIONS
  WriteTest( $file, %test_data )
    This function provides a simple way to write a single test to a file,
    following the usual template. The test data is a hash (Note: it's NOT a
    hash reference).

    Example code:

      WriteTest(
        't/somefile.t',
        test    => 'ok_changes',
        release => 0,
        comment => 'Test that Changes has an entry for current version',
        modules => {
          'Test::CheckChanges' => '0.08',
        },
      );

    This writes a test to t/somefile.t that loads Test::CheckChanges if
    available, calling the "ok_changes()" function if it is. A few knobs
    control how this works:

    *   test is the name of the subroutine to run, which has to be exported
        from the test module.

    *   release determines whether this is a release-only test, which means
        it is not executed during automated testing, even if the needed
        prerequisites are available.

    *   comment is the default comment which briefly describes the test.

    *   modules is a hash reference containing pairs of modules and their
        required versions. If no particular version is required, use 0.

  WriteXT( %tests )
    This provides a convenient way to write multiple test files using the
    default profile settings (such as which modules to require, what
    subroutine to call, whether this is a release-only test).

    Example code:

      WriteXT(
          'Test::Pod'            => 't/pod.t',
          'Test::CPAN::Meta'     => 't/meta.t',
          'Test::MinimumVersion' => 't/minimumversion.t',
          'Test::Perl::Critic'   => 't/critic.t',
      );

LIMITATIONS
    This module is still missing support for lots of other author tests.

SUPPORT
    This module is stored in an Open Repository at the following address:

    <http://svn.ali.as/cpan/trunk/Test-XT>

    Write access to the repository is made available automatically to any
    published CPAN author, and to most other volunteers on request.

    If you are able to submit your bug report in the form of new (failing)
    unit tests, or can apply your fix directly instead of submitting a
    patch, you are strongly encouraged to do so. The author currently
    maintains over 100 modules and it may take some time to deal with
    non-critical bug reports or patches.

    This will guarantee that your issue will be addressed in the next
    release of the module.

    If you cannot provide a direct test or fix, or don't have time to do so,
    then regular bug reports are still accepted and appreciated via the CPAN
    bug tracker.

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-XT>

    For other issues, for commercial enhancement and support, or to have
    your write access enabled for the repository, contact the author at the
    email address above.

AUTHORS
    Adam Kennedy <adamk@cpan.org>

    Jonathan Yu <frequency@cpan.org>

SEE ALSO
    <http://use.perl.org/~Alias/journal/38822>, which explains why this
    style of testing is beneficial to you and CPAN-at-large.

COPYRIGHT
    Copyright 2009 Adam Kennedy

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

    The full text of the license can be found in the LICENSE file included
    with this module.

