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
29       modules in your distribution, checks their POD, checks that they
30       compile 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
39       conjunction with other "Test::*" modules in the same file. It's
40       recommended that you just create a one-line test script as shown in the
41       SYNOPSIS above. However, there are options...
42
43       NOTE If you do not specify any options Test::Distribution will run all
44       test types except signature testing which must always be explicitly
45       switched on.
46
47       In the future I may change the default to run no tests at all as this
48       sounds safer. Mail me if you disagree.
49

OPTIONS

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

TEST TYPES

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

EXPOSED INTERNALS

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

INSTALLATION

168       This module uses Module::Build for its installation. To install this
169       module type the following:
170
171         perl Build.PL
172         ./Build
173         ./Build test
174         ./Build install
175
176       If you do not have Module::Build type:
177
178         perl Makefile.PL
179
180       to fetch it. Or use CPAN or CPANPLUS and fetch it "manually".
181

DEPENDENCIES

183       This module requires these other modules and libraries:
184
185        File::Basename
186        File::Find::Rule
187        File::Spec
188        Test::More
189
190       This module has these optional dependencies:
191
192        Module::CoreList
193        Test::Pod
194        Test::Pod::Coverage
195
196       If "Module::CoreList" is missing, the "prereq" tests are skipped.
197
198       If "Test::Pod" is missing, the "pod" tests are skipped.
199

TODO

201       Just because these items are in the todo list,  does not mean they will
202       actually be done. If you  think one of these  would be helpful say  so
203       - and it will then move up on my priority list.
204
205       •   Module::Build support  [currently waiting for a fix on Test::Prereq
206           ]
207

FEATURE IDEAS

209       "export" test type
210           This would mandate that there should be a test for each exported
211           symbol of each module.
212
213       Let me know what you think of these ideas. Are they necessary?
214       Unnecessary? Do you have feature requests of your own?
215

BUGS

217       To report a bug  or request an enhancement use CPAN's  excellent
218       Request Tracker.
219

SOURCE AVAILABILITY

221       This source is part of a SourceForge project which always has the
222       latest sources in svn.
223
224       http://sourceforge.net/projects/sagar-r-shah/
225

AUTHORS

227       Marcel Gruenauer <marcel@cpan.org>
228
229       Sagar R. Shah
230

OTHER CREDITS

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

COPYRIGHT & LICENSE

237       Copyright 2002-2003 Marcel Gruenauer. All rights reserved.
238
239       Copyright 2003-2007, Sagar R. Shah, All rights reserved.
240
241       This program  is free software; you can  redistribute it  and/or modify
242       it under the same terms as Perl itself.
243