NAME
Test::Distribution - perform tests on all modules of a distribution
SYNOPSIS
$ cat t/01distribution.t
use 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.
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.
"pod"
Checks for POD errors in files
"use"
This "use()"s the modules to make sure the load happens ok.
"versions"
Checks that all packages define $VERSION strings.
"description"
Checks that the following files exist:
Changes
MANIFEST
README
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".
TEST::DISTRIBUTION'S OWN PREREQUISITES
"Test::Distribution" uses "File::Find::Rule" and "Test::Pod", amongst
other modules. Each of these modules have their own rather long list of
prerequisites. If you use the CPAN shell or a package manager to install
modules, this is probably of no concern, but if you install modules
manually, you might not care to install a lot of modules just to get
"Test::Distribution" to run.
Because of this, "Test::Distribution" checks whether you have the
required modules installed and skips tests (per "Test::More" definition)
as necessary if these modules are not found. If you don't have
"Test::Pod", you can't run the "pod" tests. If you don't have
"Module::CoreList", you can't run the "prereq" tests. But if you don't
have "File::Find::Rule", all tests are skipped.
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.
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
If you find any bugs or oddities, please do inform the author.
INSTALLATION
See perlmodinstall for information and options on installing Perl
modules.
AVAILABILITY
The latest version of this module is available from the Distribution
Perl Archive Network (CPAN). Visit to find a
CPAN site near you. Or see
.
VERSION
This document describes version 1.05 of "Test::Distribution".
AUTHOR
Marcel Grünauer
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.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
perl(1), Test::More(3pm), Test::Pod(3pm), File::Find::Rule(3pm).