1Test::DistManifest(3) User Contributed Perl DocumentationTest::DistManifest(3)
2
6 Test::DistManifest - Author test that validates a package MANIFEST
7
9 version 1.012
10
12 use Test::More;
13 # This is the common idiom for author test modules like this, but see
15 # the full example in examples/checkmanifest.t and, more importantly,
16 # Adam Kennedy's article: http://use.perl.org/~Alias/journal/38822
17 eval 'use Test::DistManifest';
18 if ($@) {
19 plan skip_all => 'Test::DistManifest required to test MANIFEST';
20 }
21 manifest_ok('MANIFEST', 'MANIFEST.SKIP'); # Default options
23 manifest_ok(); # Functionally equivalent to above
25
27 This module provides a simple method of testing that a MANIFEST matches
28 the distribution.
29 It tests three things:
31 1. Everything in MANIFEST exists
33 2. Everything in the package is listed in MANIFEST, or subsequently
35 matches a regular expression mask in MANIFEST.SKIP
36 3. Nothing exists in MANIFEST that also matches a mask in
38 MANIFEST.SKIP, so as to avoid an unsatisfiable dependency
39 conditions
40 If there is no MANIFEST.SKIP included in your distribution, this module
42 will replicate the toolchain behaviour of using the default system-wide
43 MANIFEST.SKIP file. To view the contents of this file, use the command:
44 $ perldoc -m ExtUtils::MANIFEST.SKIP
46
48 By default, this module exports the following functions:
49 · manifest_ok
51
53 manifest_ok
54 manifest_ok( $manifest, $skipfile )
55 This subroutine checks the manifest list contained in $manifest by
57 using "Module::Manifest" to determine the list of files and then
58 checking for the existence of all such files. Then, it checks if there
59 are any files in the distribution that were not specified in the
60 $manifest file but do not match any regular expressions provided in the
61 $skipfile exclusion file.
62 If your MANIFEST file is generated by a module installation toolchain
64 system such as ExtUtils::MakeMaker, Module::Build or Module::Install,
65 then you shouldn't have any problems with these files. It's just a
66 helpful test to remind you to update these files, using:
67 $ make manifest # For ExtUtils::MakeMaker
69 $ ./Build manifest # For Module::Build
70 Non-Fatal Errors
72 By default, errors in the MANIFEST or MANIFEST.SKIP files are treated
73 as fatal, which really is the purpose of using "Test::DistManifest" as
74 part of your author test suite.
75 In some cases this is not desirable behaviour, such as with the Debian
77 Perl Group, which runs all tests - including author tests - as part of
78 its module packaging process. This wreaks havoc because Debian adds its
79 control files in "debian/" downstream, and that directory or its files
80 are generally not in MANIFEST.SKIP.
81 By setting the environment variable MANIFEST_WARN_ONLY to a true value,
83 errors will be non-fatal - they show up as diagnostic messages only,
84 but all tests pass from the perspective of "Test::Harness".
85 This can be used in a test script as:
87 $ENV{MANIFEST_WARN_ONLY} = 1;
89 or from other shell scripts as:
91 export MANIFEST_WARN_ONLY=1
93 Note that parsing errors in MANIFEST and circular dependencies will
95 always be considered fatal. The author is not aware of any cases where
96 other behaviour would be useful.
97
99 This module internally plans 4 tests:
100 1. MANIFEST can be parsed by "Module::Manifest"
102 2. Check which files exist in the distribution directory that do not
104 match an existing regular expression in MANIFEST.SKIP and not
105 listed in the MANIFEST file. These files should either be excluded
106 from the test by addition of a mask in MANIFEST.SKIP (in the case
107 of temporary development or test files) or should be included in
108 the MANIFEST.
109 3. Check which files are specified in MANIFEST but do not exist on the
111 disk. This usually occurs when one deletes a test or similar
112 script from the distribution, or accidentally moves it.
113 4. Check which files are specified in both MANIFEST and MANIFEST.SKIP.
115 This is clearly an unsatisfiable condition, since the file in
116 question cannot be expected to be included while also
117 simultaneously ignored.
118 If you want to run tests on multiple different MANIFEST files, you can
120 simply pass 'no_plan' to the import function, like so:
121 use Test::DistManifest 'no_plan';
123 # Multiple tests work properly now
125 manifest_ok('MANIFEST', 'MANIFEST.SKIP');
126 manifest_ok();
127 manifest_ok('MANIFEST.OTHER', 'MANIFEST.SKIP');
128 I doubt this will be useful to users of this module. However, this is
130 used internally for testing and it might be helpful to you. You can
131 also plan more tests, but keep in mind that the idea of "3 internal
132 tests" may change in the future.
133 Example code:
135 use Test::DistManifest tests => 5;
137 manifest_ok(); # 4 tests
138 ok(1, 'is 1 true?');
139
141 · Thanks to Adam Kennedy for developing Module::Manifest, which
142 provides much of the core functionality for these tests.
143 · Thanks to Apocalypse <apocal@cpan.org>, for helping me track down
145 an obscure bug caused by circular dependencies: when files are
146 expected by MANIFEST but explictly skipped by MANIFEST.SKIP.
147
149 Test::CheckManifest, a module providing similar functionality
150
152 · There is currently no way to test a MANIFEST/MANIFEST.SKIP without
153 having the files actually exist on disk. I am planning for this to
154 change in the future.
155 · This module has not been tested very thoroughly with Unicode.
157 · This module does not produce any useful diagnostic messages in
159 terms of how to correct the situation. Hopefully this will be
160 obvious for anybody using the module; the emphasis should be on
161 generating helpful error messages.
162
164 Please report any bugs or feature requests on the bugtracker website
165 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-DistManifest
166 When submitting a bug or request, please include a test-file or a patch
168 to an existing test-file that illustrates the bug or desired feature.
169
171 Jonathan Yu <jawnsy@cpan.org>
172
174 This software is copyright (c) 2012 by Jonathan Yu <jawnsy@cpan.org>.
175 This is free software; you can redistribute it and/or modify it under
177 the same terms as the Perl 5 programming language system itself.
178perl v5.16.3 2012-04-22 Test::DistManifest(3)