Test::DistManifest(3) User Contributed Perl DocumentationTest::DistManifest(3)NAMETest::DistManifest - Author test that validates a package MANIFEST
VERSION
version 1.011
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
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
EXPORTS
By default, this module exports the following functions:
· manifest_ok
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?');
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.
SEE ALSO
Test::CheckManifest, a module providing similar functionality
CAVEATS
· 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.
BUGS
Please report any bugs or feature requests on the bugtracker website
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-DistManifest
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
AUTHOR
Jonathan Yu <jawnsy@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Jonathan Yu <jawnsy@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.14.1 2011-04-24 Test::DistManifest(3)
