NAME¶
Test::DistManifest - Author test that validates a package MANIFEST
VERSION¶
Version 1.009 ($Id: DistManifest.pm 10671 2009-12-29 01:49:23Z
FREQUENCY@cpan.org $)
EXPORTS¶
By default, this module exports the following functions:
- •
- manifest_ok
DESCRIPTION¶
This module provides a simple method of testing that a MANIFEST matches the
distribution.
It tests three things:
- 1.
- Everything in MANIFEST exists
- 2.
- Everything in the package is listed in MANIFEST, or
subsequently matches a regular expression mask in
MANIFEST.SKIP
- 3.
- Nothing exists in MANIFEST that also matches a mask
in MANIFEST.SKIP, so as to avoid an unsatisfiable dependency
conditions
If there is no
MANIFEST.SKIP included in your distribution, this module
will replicate the toolchain behaviour of using the default system-wide
MANIFEST.SKIP file. To view the contents of this file, use the command:
$ perldoc -m ExtUtils::MANIFEST.SKIP
SYNOPSIS¶
use Test::More;
# This is the common idiom for author test modules like this, but see
# the full example in examples/checkmanifest.t and, more importantly,
# Adam Kennedy's article: http://use.perl.org/~Alias/journal/38822
eval 'use Test::DistManifest';
if ($@) {
plan skip_all => 'Test::DistManifest required to test MANIFEST';
}
manifest_ok('MANIFEST', 'MANIFEST.SKIP'); # Default options
manifest_ok(); # Functionally equivalent to above
COMPATIBILITY¶
This module was tested under Perl 5.10.0, using Debian Linux. However, because
it's Pure Perl and doesn't do anything too obscure, it should be compatible
with any version of Perl that supports its prerequisite modules.
If you encounter any problems on a different version or architecture, please
contact the maintainer.
FUNCTIONS¶
manifest_ok¶
manifest_ok( $manifest, $skipfile )
This subroutine checks the manifest list contained in $manifest by using
"Module::Manifest" to determine the list of files and then checking
for the existence of all such files. Then, it checks if there are any files in
the distribution that were not specified in the $manifest file but do not
match any regular expressions provided in the $skipfile exclusion file.
If your MANIFEST file is generated by a module installation toolchain system
such as ExtUtils::MakeMaker, Module::Build or Module::Install, then you
shouldn't have any problems with these files. It's just a helpful test to
remind you to update these files, using:
$ make manifest # For ExtUtils::MakeMaker
$ ./Build manifest # For Module::Build
Non-Fatal Errors¶
By default, errors in the
MANIFEST or
MANIFEST.SKIP files are
treated as fatal, which really is the purpose of using
"Test::DistManifest" as part of your author test suite.
In some cases this is not desirable behaviour, such as with the Debian Perl
Group, which runs all tests - including author tests - as part of its module
packaging process. This wreaks havoc because Debian adds its control files in
"debian/" downstream, and that directory or its files are generally
not in
MANIFEST.SKIP.
By setting the environment variable
MANIFEST_WARN_ONLY to a true value,
errors will be non-fatal - they show up as diagnostic messages only, but all
tests pass from the perspective of "Test::Harness".
This can be used in a test script as:
$ENV{MANIFEST_WARN_ONLY} = 1;
or from other shell scripts as:
export MANIFEST_WARN_ONLY=1
Note that parsing errors in
MANIFEST and circular dependencies will
always be considered fatal. The author is not aware of any cases where other
behaviour would be useful.
GUTS¶
This module internally plans 4 tests:
- 1.
- MANIFEST can be parsed by
"Module::Manifest"
- 2.
- Check which files exist in the distribution directory that
do not match an existing regular expression in MANIFEST.SKIP and
not listed in the MANIFEST file. These files should either be
excluded from the test by addition of a mask in MANIFEST.SKIP (in the case
of temporary development or test files) or should be included in the
MANIFEST.
- 3.
- Check which files are specified in MANIFEST but do
not exist on the disk. This usually occurs when one deletes a test or
similar script from the distribution, or accidentally moves it.
- 4.
- Check which files are specified in both MANIFEST and
MANIFEST.SKIP. This is clearly an unsatisfiable condition, since
the file in question cannot be expected to be included while also
simultaneously ignored.
If you want to run tests on multiple different MANIFEST files, you can simply
pass 'no_plan' to the import function, like so:
use Test::DistManifest 'no_plan';
# Multiple tests work properly now
manifest_ok('MANIFEST', 'MANIFEST.SKIP');
manifest_ok();
manifest_ok('MANIFEST.OTHER', 'MANIFEST.SKIP');
I doubt this will be useful to users of this module. However, this is used
internally for testing and it might be helpful to you. You can also plan more
tests, but keep in mind that the idea of "3 internal tests" may
change in the future.
Example code:
use Test::DistManifest tests => 5;
manifest_ok(); # 4 tests
ok(1, 'is 1 true?');
AUTHOR¶
Jonathan Yu <jawnsy@cpan.org>
CONTRIBUTORS¶
Your name here ;-)
ACKNOWLEDGEMENTS¶
- •
- Thanks to Adam Kennedy for developing Module::Manifest,
which provides much of the core functionality for these tests.
- •
- Thanks to Apocalypse <apocal@cpan.org>, for helping
me track down an obscure bug caused by circular dependencies: when files
are expected by MANIFEST but explictly skipped by MANIFEST.SKIP.
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc Test::DistManifest
You can also look for information at:
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Test-Dist-Manifest>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/Test-Dist-Manifest>
- •
- Search CPAN
<http://search.cpan.org/dist/Test-Dist-Manifest>
- •
- CPAN Request Tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Dist-Manifest>
- •
- CPAN Testing Service (Kwalitee Tests)
<http://cpants.perl.org/dist/overview/Test-DistManifest>
REPOSITORY¶
You can access the most recent development version of this module at:
<
http://svn.ali.as/cpan/trunk/Test-DistManifest>
If you are a CPAN developer and would like to make modifications to the code
base, please contact Adam Kennedy <adamk@cpan.org>, the repository
administrator. I only ask that you contact me first to discuss the changes you
wish to make to the distribution.
FEEDBACK¶
Please send relevant comments, rotten tomatoes and suggestions directly to the
maintainer noted above.
If you have a bug report or feature request, please file them on the CPAN
Request Tracker at <
http://rt.cpan.org>. If you are able to submit your
bug report in the form of failing unit tests, you are
strongly
encouraged to do so.
SEE ALSO¶
Test::CheckManifest, a module providing similar functionality
CAVEATS¶
KNOWN BUGS¶
There are no known bugs as of this release.
LIMITATIONS¶
- •
- There is currently no way to test a MANIFEST/MANIFEST.SKIP
without having the files actually exist on disk. I am planning for this to
change in the future.
- •
- This module has not been tested very thoroughly with
Unicode.
- •
- This module does not produce any useful diagnostic messages
in terms of how to correct the situation. Hopefully this will be obvious
for anybody using the module; the emphasis should be on generating helpful
error messages.
QUALITY ASSURANCE METRICS¶
TEST COVERAGE¶
File stmt bran cond sub pod total
----------------------- ------ ------ ------ ------ ------ ------
Test/DistManifest.pm 96.1 95.8 100.0 100.0 100.0 96.8
LICENSE¶
Copyright 2008-2009 by Jonathan Yu <jawnsy@cpan.org>
This package is distributed under the same terms as Perl itself. Please see the
LICENSE file included in this distribution for full details of these
terms.
DISCLAIMER OF WARRANTY¶
This software is provided by the copyright holders and contributors "AS
IS" and ANY EXPRESS OR IMPLIED WARRANTIES, including, but not limited to,
the IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.
In no event shall the copyright owner or contributors be liable for any direct,
indirect, incidental, special, exemplary or consequential damages (including,
but not limited to, procurement of substitute goods or services; loss of use,
data or profits; or business interruption) however caused and on any theory of
liability, whether in contract, strict liability or tort (including negligence
or otherwise) arising in any way out of the use of this software, even if
advised of the possibility of such damage.