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 the same $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.

   *   Include an example of a 01distribution.t that only uses
       Test::Distribution if it is installed. This way module authors do
       not need to make it a required module. [use a variant of the require
       method .. .see man perlfunc: require]

   *   Module::Build support

   *   Go through patches sent to original author

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.

   "podcoverage" test type
       This would pass all modules through Pod::Coverage.

   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 use CPAN's excellent Request
   Tracker, either via the web:

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

   or via email:

   [email protected]

AUTHORS
   Marcel Gr�nauer <[email protected]>

   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).

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.