Test::...nifest(3pm)

💖 NAME 💖

Test::DistManifest — an author test that validates a package MANIFEST ✨ (it lives in section 3pm of your friendly neighbourhood Perl docs, bestie)

---

🌸 VERSION 🌸

version 1.014 — yes she's on 1.014, she's thriving 💅

---

🦋 SYNOPSIS 🦋

okay so this is the common idiom for author test modules like this one, but like, peep the full example in examples/checkmanifest.t and — more importantly — Adam Kennedy's article: <http://use.perl.org/use.perl.org/_Alias/journal/38822.html> 👑

use Test::More;
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 gives you a simple little method of testing that a MANIFEST actually matches the distribution. no cap 🫶

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

---

🎀 EXPORTS 🎀

By default, this module exports the following functions:

• manifest_ok

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

---

✨ 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 it checks for the existence of all such files. Then — plot twist — it checks if there are any files in the distribution that were not specified in the $manifest file but also don't 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 lil 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 whole purpose of using Test::DistManifest as part of your author test suite. periodt.

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 four 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 explicitly skipped by MANIFEST.SKIP. 🐛

---

⭐ SEE ALSO ⭐

• Test::CheckManifest, a module providing similar functionality
• Module::Manifest
• Dist::Zilla::Plugin::Test::DistManifest
• Test::Manifest

---

🍓 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. 💀

---

💅 AUTHOR 💅

Jonathan Yu <jawnsy@cpan.org>

---

🌸 COPYRIGHT AND LICENSE 🌸

This software is copyright (c) 2008 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.

---

🧚 CONTRIBUTOR 🧚

Karen Etheridge <ether@cpan.org>

---

and that's the whole page, bestie — documented by the lovely folks running perl v5.34.0, dated 2022-06-17, filed under Test::...nifest(3pm) because apparently someone was too iconic to type the whole name 😭 slay, go write that MANIFEST 💖✨