Test::Distribution - perform tests on all modules of a distribution
$ cat t/01distribution.t use Test::Distribution; $ make test ...
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...
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
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
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
not. In this case only the tests specified in
only, but not
not are run (if this makes any sense).
Here is a description of the types of tests available.
Checks for POD errors in files
use()s the modules to make sure the load happens ok.
Checks that all packages define
Checks that the following files exist:
Checks whether all
use()d modules that aren't in the perl core are also mentioned in Makefile.PL's
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.
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.
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
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
This is the number of tests that this module has run, based on your specifications.
This would check the MANIFEST's integrity.
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?
If you find any bugs or oddities, please do inform the author.
See perlmodinstall for information and options on installing Perl modules.
The latest version of this module is available from the Distribution Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.
This document describes version 1.05 of
Marcel Grünauer <firstname.lastname@example.org>
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 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.