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
testsargument when usingTest::Moreor other test modules as the plan is handled byTest::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
usetests, 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
versionsoption, theuseoption 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 ausetest.The value for
onlycan 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
notcan be a string or a reference to a list of strings. Although it doesn't seem to make much sense, you can use bothonlyandnot. In this case only the tests specified inonly, but notnotare 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:
prereq-
Checks whether all
use()d modules that aren't in the perl core are also mentioned in Makefile.PL'sPREREQ_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
$VERSIONstrings.
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.pmis expected to be available viause 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 installIf you do not have Module::Build type:
perl Makefile.PLto 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::MoreThis module has these optional dependencies:
Module::CoreList
Test::PodIf 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.
Consider Paul Hughes' patch for optionally using the MANIFEST to define which files to run tests on
Allow files to have a different version number from the distribution
Module::Build support [currently waiting for a fix on Test::Prereq ]
podcoverage action via Test::Pod::Coverage
FEATURE IDEAS
manifesttest type-
This would check the MANIFEST's integrity.
exporttest 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 use CPAN's excellent Request Tracker, either via the web:
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Distribution
or via email:
bug-test-distribution@rt.cpan.org
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).