Test::Distribution(3pm)

1Test::Distribution(3) User Contributed Perl DocumentationTest::Distribution(3)
2
3
4

NAME

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

SYNOPSIS

9         $ cat t/01distribution.t
10         use Test::More;
11
12         BEGIN {
13               eval {
14                       require Test::Distribution;
15               };
16               if($@) {
17                       plan skip_all => 'Test::Distribution not installed';
18               }
19               else {
20                       import Test::Distribution;
21               }
22          }
23
24         $ make test
25         ...
26

DESCRIPTION

28       When using this module in a test script, it goes through all the mod‐
29       ules in your distribution, checks their POD, checks that they compile
30       ok and checks that they all define a  $VERSION.
31
32       This module also performs a numer of test on  the distribution itself.
33       It checks that your files match your  SIGNATURE file if you  have one.
34       It checks that your distribution  isn't missing certain 'core'
35       description files.  It checks to see you havent' missed out listing any
36       pre-requisites in Makefile.PL.
37
38       It defines its own testing plan, so you usually don't use it in con‐
39       junction with other "Test::*" modules in the same file. It's recom‐
40       mended that you just create a one-line test script as shown in the SYN‐
41       OPSIS above. However, there are options...
42

OPTIONS

44       On the line in which you "use()" this module, you can specify named
45       arguments that influence the testing behavior.
46
47       "tests => NUMBER"
48           Specifies that in addition to the tests run by this module, your
49           test script will run additional tests. In other words, this value
50           influences the test plan. For example:
51
52             use Test::Distribution tests => 1;
53             use Test::More;
54             is($foo, $bar, 'baz');
55
56           It is important that you don't specify a "tests" argument when
57           using "Test::More" or other test modules as the plan is handled by
58           "Test::Distribution".
59
60       "only => STRING⎪LIST"
61           Specifies that only certain sets of tests are to be run. Possible
62           values are those mentioned in TEST TYPES below. For example, if you
63           only want to run the POD tests, you could say:
64
65             use Test::Distribution only => 'pod';
66
67           To specify that you only want to run the POD tests and the "use"
68           tests, and also that you are going to run two tests of your own,
69           use:
70
71             use Test::Distribution
72               only  => [ qw/pod use/ ],
73               tests => 2;
74
75           Note that when you specify the "versions" option, the "use" option
76           is automatically added. This is because in order to get a module's
77           $VERSION, it has to be loaded. In this case we might as well run a
78           "use" test.
79
80           The value for "only" can be a string or a reference to a list of
81           strings.
82
83       "not => STRING⎪LIST"
84           Specifies that certain types of tests should not be run. All tests
85           not mentioned in this argument are run. For example, if you want to
86           test everything except the POD, use:
87
88             use Test::Distribution
89               not => 'pod';
90
91           The value for "not" can be a string or a reference to a list of
92           strings. Although it doesn't seem to make much sense, you can use
93           both "only" and "not". In this case only the tests specified in
94           "only", but not "not" are run (if this makes any sense).
95
96       "distversion"
97           If you test this to a true value, as well as testing that each mod‐
98           ule has a $VERSION defined, Test::Distribution will also ensure
99           that the $VERSION matches that of the distribution.
100
101       "podcoveropts"
102           You can set this to be a hash reference of options to pass to
103           Test::Pod::Coverage's pod_coverage_ok method (which in turn gets
104           passed to Pod::Coverage.
105

TEST TYPES

107       Here is a description of the types of tests available.
108
109       "description"
110           Checks that the following files exist:
111
112           Changes  or ChangeLog
113           MANIFEST
114           README
115           Build.PL or Makefile.PL
116       "prereq"
117           Checks whether all "use()"d modules that aren't in the perl core
118           are also mentioned in Makefile.PL's "PREREQ_PM".
119
120       "pod"
121           Checks for POD errors in files
122
123       "podcover"
124           Checks for Pod Coverage
125
126       "sig"
127           If the distribution   has a SIGNATURE  file, checks  the  SIGNATURE
128           matches  the files.
129
130       "use"
131           This "use()"s the modules to make sure the load happens ok.
132
133       "versions"
134           Checks that all packages define $VERSION strings.
135

EXPOSED INTERNALS

137       There are a few subroutines to help you see what this module is doing.
138       Note that these subroutines are neither exported nor exportable, so you
139       have to call them fully qualified.
140
141       "Test::Distribution::packages()"
142           This is a list of packages that have been found. That is, we assume
143           that each file contains a package of the name indicated by the
144           file's relative position. For example, a file in
145           "blib/lib/Foo/Bar.pm" is expected to be available via "use
146           Foo::Bar".
147
148       "Test::Distribution::files()"
149           This is a list of files that tests have been run on. The filenames
150           are relative to the distribution's root directory, so they start
151           with "blib/lib".
152
153       "Test::Distribution::num_tests()"
154           This is the number of tests that this module has run, based on your
155           specifications.
156

INSTALLATION

158       This module uses Module::Build for its installation. To install this
159       module type the following:
160
161         perl Build.PL
162         ./Build
163         ./Build test
164         ./Build install
165
166       If you do not have Module::Build type:
167
168         perl Makefile.PL
169
170       to fetch it. Or use CPAN or CPANPLUS and fetch it "manually".
171

DEPENDENCIES

173       This module requires these other modules and libraries:
174
175        File::Basename
176        File::Find::Rule
177        File::Spec
178        Test::More
179
180       This module has these optional dependencies:
181
182        Module::CoreList
183        Test::Pod
184        Test::Pod::Coverage
185
186       If "Module::CoreList" is missing, the "prereq" tests are skipped.
187
188       If "Test::Pod" is missing, the "pod" tests are skipped.
189

TODO

191       Just because these items are in the todo list,  does not mean they will
192       actually be done. If you  think one of these  would be helpful say  so
193       - and it will then move up on my priority list.
194
195       ·   Module::Build support  [currently waiting for a fix on Test::Prereq
196           ]
197

FEATURE IDEAS

199       "export" test type
200           This would mandate that there should be a test for each exported
201           symbol of each module.
202
203       Let me know what you think of these ideas. Are they necessary? Unneces‐
204       sary? Do you have feature requests of your own?
205

BUGS

207       To report a bug  or request an enhancement use CPAN's  excellent
208       Request Tracker.
209

AUTHORS

211       Marcel Gruenauer <marcel@cpan.org>
212
213       Sagar R. Shah
214

OTHER CREDITS

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

COPYRIGHT & LICENSE

221       Copyright 2002-2003 Marcel Gruenauer. All rights reserved.
222
223       Copyright 2003-2005, Sagar R. Shah, All rights reserved.
224
225       This library is free software; you can redistribute it and/or modify it
226       under the same terms as Perl itself.
227