1Test::Distribution(3) User Contributed Perl DocumentationTest::Distribution(3)
2
6 Test::Distribution - perform tests on all modules of a distribution
7
9 $ cat t/01distribution.t
10 use Test::More;
11 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 $ make test
25 ...
26
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 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 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 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 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
51 On the line in which you use() this module, you can specify named
52 arguments that influence the testing behavior.
53 "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 use Test::Distribution tests => 1;
60 use Test::More;
61 is($foo, $bar, 'baz');
62 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 DEPRECATED FEATURE. I plan to remove this in the future unless I'm
68 contacted by someone that says they find this useful.
69 "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 use Test::Distribution only => 'pod';
76 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 use Test::Distribution
82 only => [ qw/pod use/ ],
83 tests => 2;
84 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 The value for "only" can be a string or a reference to a list of
91 strings.
92 "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 use Test::Distribution
99 not => 'pod';
100 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 "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 "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
117 Here is a description of the types of tests available.
118 "description"
120 Checks that the following files exist:
121 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 are
128 also mentioned in Makefile.PL's "PREREQ_PM".
129 "pod"
131 Checks for POD errors in files
132 "podcover"
134 Checks for Pod Coverage
135 "sig"
137 If the distribution has a SIGNATURE file, checks the SIGNATURE
138 matches the files.
139 "use"
141 This use()s the modules to make sure the load happens ok.
142 "versions"
144 Checks that all packages define $VERSION strings.
145
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 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 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 Test::Distribution::num_tests()
164 This is the number of tests that this module has run, based on your
165 specifications.
166
168 This module uses Module::Build for its installation. To install this
169 module type the following:
170 perl Build.PL
172 ./Build
173 ./Build test
174 ./Build install
175 If you do not have Module::Build type:
177 perl Makefile.PL
179 to fetch it. Or use CPAN or CPANPLUS and fetch it "manually".
181
183 This module requires these other modules and libraries:
184 File::Basename
186 File::Find::Rule
187 File::Spec
188 Test::More
189 This module has these optional dependencies:
191 Module::CoreList
193 Test::Pod
194 Test::Pod::Coverage
195 If "Module::CoreList" is missing, the "prereq" tests are skipped.
197 If "Test::Pod" is missing, the "pod" tests are skipped.
199
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 • Module::Build support [currently waiting for a fix on Test::Prereq
206 ]
207
209 "export" test type
210 This would mandate that there should be a test for each exported
211 symbol of each module.
212 Let me know what you think of these ideas. Are they necessary?
214 Unnecessary? Do you have feature requests of your own?
215
217 To report a bug or request an enhancement use CPAN's excellent
218 Request Tracker.
219
221 This source is part of a SourceForge project which always has the
222 latest sources in svn.
223 http://sourceforge.net/projects/sagar-r-shah/
225
227 Marcel Grünauer <marcel@cpan.org>
228 Sagar R. Shah
230
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
237 Copyright 2002-2003 Marcel Grünauer. All rights reserved.
238 Copyright 2003-2007, Sagar R. Shah, All rights reserved.
240 This program is free software; you can redistribute it and/or modify
242 it under the same terms as Perl itself.
243
245 perl(1), ExtUtils::Manifest(3pm), File::Find::Rule(3pm),
246 Module::CoreList(3pm), Test::More(3pm), Test::Pod(3pm),
247 Test::Pod::Coverage(3pm), Test::Signature(3pm).
248perl v5.36.0 2023-01-20 Test::Distribution(3)