NAME
    Test::Distribution - perform tests on all modules of a distribution

SYNOPSIS
      $ cat t/01distribution.t
      use Test::More;

      BEGIN {
            eval {
                    require Test::Distribution;
            };
            if($@) {
                    plan skip_all => 'Test::Distribution not installed';
            }
            else {
                    import Test::Distribution;
            }
       }

      $ make test
      ...

DESCRIPTION
    When using this module in a test script, it goes through all the modules
    in your distribution, checks their POD, checks that they compile ok and
    checks that they all define a $VERSION.

    This module also performs a numer of test on the distribution itself. It
    checks that your files match your SIGNATURE file if you have one. It
    checks that your distribution isn't missing certain 'core' description
    files. It checks to see you havent' missed out listing any
    pre-requisites in Makefile.PL.

    It defines its own testing plan, so you usually don't use it in
    conjunction with other "Test::*" modules in the same file. It's
    recommended that you just create a one-line test script as shown in the
    SYNOPSIS above. However, there are options...

OPTIONS
    On the line in which you "use()" this module, you can specify named
    arguments that influence the testing behavior.

    "tests => NUMBER"
        Specifies that in addition to the tests run by this module, your
        test script will run additional tests. In other words, this value
        influences the test plan. For example:

          use Test::Distribution tests => 1;
          use Test::More;
          is($foo, $bar, 'baz');

        It is important that you don't specify a "tests" argument when using
        "Test::More" or other test modules as the plan is handled by
        "Test::Distribution".

    "only => STRING|LIST"
        Specifies that only certain sets of tests are to be run. Possible
        values are those mentioned in TEST TYPES below. For example, if you
        only want to run the POD tests, you could say:

          use Test::Distribution only => 'pod';

        To specify that you only want to run the POD tests and the "use"
        tests, and also that you are going to run two tests of your own,
        use:

          use Test::Distribution
            only  => [ qw/pod use/ ],
            tests => 2;

        Note that when you specify the "versions" option, the "use" option
        is automatically added. This is because in order to get a module's
        $VERSION, it has to be loaded. In this case we might as well run a
        "use" test.

        The value for "only" can be a string or a reference to a list of
        strings.

    "not => STRING|LIST"
        Specifies that certain types of tests should not be run. All tests
        not mentioned in this argument are run. For example, if you want to
        test everything except the POD, use:

          use Test::Distribution
            not => 'pod';

        The value for "not" can be a string or a reference to a list of
        strings. Although it doesn't seem to make much sense, you can use
        both "only" and "not". In this case only the tests specified in
        "only", but not "not" are run (if this makes any sense).

TEST TYPES
    Here is a description of the types of tests available.

    "description"
        Checks that the following files exist:

        Changes
        MANIFEST
        README
        Build.PL or Makefile.PL

    "prereq"
        Checks whether all "use()"d modules that aren't in the perl core are
        also mentioned in Makefile.PL's "PREREQ_PM".

    "pod"
        Checks for POD errors in files

    "sig"
        If the distribution has a SIGNATURE file, checks the SIGNATURE
        matches the files.

    "use"
        This "use()"s the modules to make sure the load happens ok.

    "versions"
        Checks that all packages define $VERSION strings.

EXPOSED INTERNALS
    There are a few subroutines to help you see what this module is doing.
    Note that these subroutines are neither exported nor exportable, so you
    have to call them fully qualified.

    "Test::Distribution::packages()"
        This is a list of packages that have been found. That is, we assume
        that each file contains a package of the name indicated by the
        file's relative position. For example, a file in
        "blib/lib/Foo/Bar.pm" is expected to be available via "use
        Foo::Bar".

    "Test::Distribution::files()"
        This is a list of files that tests have been run on. The filenames
        are relative to the distribution's root directory, so they start
        with "blib/lib".

    "Test::Distribution::num_tests()"
        This is the number of tests that this module has run, based on your
        specifications.

INSTALLATION
    This module uses Module::Build for its installation. To install this
    module type the following:

      perl Build.PL
      ./Build
      ./Build test
      ./Build install

    If you do not have Module::Build type:

      perl Makefile.PL

    to fetch it. Or use CPAN or CPANPLUS and fetch it "manually".

DEPENDENCIES
    This module requires these other modules and libraries:

     File::Basename
     File::Find::Rule
     File::Spec
     Test::More

    This module has these optional dependencies:

     Module::CoreList
     Test::Pod

    If "Module::CoreList" is missing, the "prereq" tests are skipped.

    If "Test::Pod" is missing, the "pod" tests are skipped.

TODO
    Just because these items are in the todo list, does not mean they will
    actually be done. If you think one of these would be helpful say so -
    and it will then move up on my priority list.

    *   Add back the funcionality to check that $VERSION in each module
        matches the distribution version - but as an optional feature.
        (Requested by David A Golden)

    *   Module::Build support [currently waiting for a fix on Test::Prereq ]

    *   podcoverage action via Test::Pod::Coverage

FEATURE IDEAS
    "manifest" test type
        This would check the MANIFEST's integrity.

    "export" test type
        This would mandate that there should be a test for each exported
        symbol of each module.

    Let me know what you think of these ideas. Are they necessary?
    Unnecessary? Do you have feature requests of your own?

BUGS
    To report a bug or request an enhancement DO NOT use CPAN's excellent
    Request Tracker. As it currently does not support passing ownership of a
    bug queue when someone else takes over a module (I'm not the original
    author of this module)

    Please email me: sagarshah AT softhome.net

AUTHORS
    Marcel Grünauer <marcel@cpan.org>

    Sagar R. Shah

OTHER CREDITS
    This module was inspired by a use.perl.org journal entry by "brian d
    foy" (see <http://use.perl.org/~brian_d_foy/journal/7463>) where he
    describes an idea by Andy Lester.

COPYRIGHT
    Copyright 2002-2003 Marcel Grünauer. All rights reserved.

    Copyright 2003, Sagar R. Shah, All rights reserved.

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

SEE ALSO
    perl(1), File::Find::Rule(3pm), Test::More(3pm), Test::Pod(3pm),
    Test::Signature(3pm).