Test::DistManifest - Author test that validates a package MANIFEST

Test-DistManifest documentation Contained in the Test-DistManifest distribution.

Index

Code Index:

NAME

Top

Test::DistManifest - Author test that validates a package MANIFEST

VERSION

Top

version 1.011

SYNOPSIS

Top

  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

Top

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

Top

By default, this module exports the following functions:

* manifest_ok

FUNCTIONS

Top

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

Top

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

Top

SEE ALSO

Top

Test::CheckManifest, a module providing similar functionality

CAVEATS

Top

BUGS

Top

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

Top

Jonathan Yu <jawnsy@cpan.org>

COPYRIGHT AND LICENSE

Top

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.

Test-DistManifest documentation Contained in the Test-DistManifest distribution. 
package Test::DistManifest;
BEGIN {
  $Test::DistManifest::VERSION = '1.011';
}
# ABSTRACT: Author test that validates a package MANIFEST

use strict;
use warnings;
use Carp ();


# File management commands
use Cwd ();
use File::Spec; # Portability
use File::Spec::Unix; # To get UNIX-style paths
use File::Find (); # Traverse the filesystem tree

use Module::Manifest;
use Test::Builder;

my $test = Test::Builder->new;

my @EXPORTS = (
  'manifest_ok',
);

# These platforms were copied from File::Spec
my %platforms = (
  MacOS   => 1,
  MSWin32 => 1,
  os2     => 1,
  VMS     => 1,
  epoc    => 1,
  NetWare => 1,
  symbian => 1,
  dos     => 1,
  cygwin  => 1,
);

# Looking at other Test modules this seems to be an ad-hoc standard
sub import {
  my ($self, @plan) = @_;
  my $caller = caller;

  {
    no strict 'refs';
    for my $func (@EXPORTS) {
      *{$caller . '::' . $func} = \&{$func};
    }
  }

  $test->exported_to($caller);
  $test->plan(@plan);
  return;
}


sub manifest_ok {
  my $warn_only = $ENV{MANIFEST_WARN_ONLY} || 0;

  my $manifile = shift || 'MANIFEST';
  my $skipfile = shift || 'MANIFEST.SKIP';

  my $root = Cwd::getcwd(); # this is Build.PL's Cwd
  my $manifest = Module::Manifest->new;

  unless ($test->has_plan) {
    $test->plan(tests => 4);
  }

  # Try to parse the MANIFEST and MANIFEST.SKIP files
  eval {
    $manifest->open(manifest => $manifile);
  };
  if ($@) {
    $test->diag($!);
  }
  $test->ok(!$@, 'Parse MANIFEST or equivalent');

  eval {
    $manifest->open(skip => $skipfile);
  };
  if ($@) {
    $test->diag('Unable to parse MANIFEST.SKIP file:');
    $test->diag($!);
    $test->diag('Using default skip data from ExtUtils::Manifest 1.58');
    $manifest->parse( skip => [
      # Version control files
      '\bRCS\b',
      '\bCVS\b',
      '\bSCCS\b',
      ',v$',
      '\B\.svn\b',
      '\B\.git\b',
      '\B\.gitignore\b',
      '\b_darcs\b',
      '\B\.cvsignore$',
      # Build remnants
      '\bMANIFEST\.bak',
      '\bMakefile$',
      '\bblib/',
      '\bMakeMaker-\d',
      '\bpm_to_blib\.ts$',
      '\bpm_to_blib$',
      '\bblibdirs\.ts$',
      '\bBuild$',
      '\b_build/',
      '\bBuild.bat$',
      '\bBuild.COM$',
      '\bBUILD.COM$',
      '\bbuild.com$',
      '^MYMETA\.',
      # Temporary and backup files
      '~$',
      '\.old$',
      '\#$',
      '\b\.#',
      '\.bak$',
      '\.tmp$',
      '\.#',
      '\.rej$',
      # Mac OSX metadata
      '\B\.DS_Store',
      '\B\._',
      # Devel::Cover files
      '\bcover_db\b',
      '\bcovered\b',
    ]);
  }

  my @files;
  # Callback function called by File::Find
  my $closure = sub {
    # Trim off the package root to determine the relative path.
    my $path = File::Spec->abs2rel($File::Find::name, $root);

    # Portably deal with different OSes
    if ($platforms{$^O}) { # Check if we are on a non-Unix platform
      # Get path info from File::Spec, split apart
      my (undef, $dir, $file) = File::Spec->splitpath($path);
      my @dir = File::Spec->splitdir($dir);

      # Reconstruct the path in Unix-style
      $dir = File::Spec::Unix->catdir(@dir);
      $path = File::Spec::Unix->catpath(undef, $dir, $file);
    }

    # Test that the path is a file and then make sure it's not skipped
    if (-f $path && !$manifest->skipped($path)) {
      push @files, $path;
    }
    return;
  };

  # Traverse the directory recursively
  File::Find::find({
    wanted            => $closure,
    untaint           => 1,
    no_chdir          => 1,
  }, $root);

  # The two arrays have no duplicates. Thus we loop through them and
  # add the result to a hash.
  my %seen;
  # Allocate buckets for the hash
  keys(%seen) = 2 * scalar(@files);
  foreach my $path (@files, $manifest->files) {
    $seen{$path}++;
  }

  my $flag = 1;
  foreach my $path (@files) {
    # Skip the path if it was seen twice (the expected condition)
    next if ($seen{$path} == 2);

    # Oh no, we have files in @files not in $manifest->files
    if ($flag == 1) {
      $test->diag('Distribution files are missing in MANIFEST:');
      $flag = 0;
    }
    $test->diag($path);
  }
  $test->ok($warn_only || $flag, 'All files are listed in MANIFEST or ' .
    'skipped');

  # Reset the flag and test $manifest->files now
  $flag = 1;
  my @circular = (); # for detecting circular logic
  foreach my $path ($manifest->files) {
    # Skip the path if it was seen twice (the expected condition)
    next if ($seen{$path} == 2);

    # If the file should exist but is passed by MANIFEST.SKIP, we have
    # a strange circular logic condition.
    if ($manifest->skipped($path)) {
      push (@circular, $path);
      next;
    }

    # Oh no, we have files in $manifest->files not in @files
    if ($flag == 1) {
      $test->diag('MANIFEST lists the following missing files:');
      $flag = 0;
    }
    $test->diag($path);
  }
  $test->ok($warn_only || $flag, 'All files listed in MANIFEST exist ' .
    'on disk');

  # Test for circular dependencies
  $flag = (scalar @circular == 0) ? 1 : 0;
  if (not $flag) {
    $test->diag('MANIFEST and MANIFEST.SKIP have circular dependencies:');
    foreach my $path (@circular) {
      $test->diag($path);
    }
  }
  $test->ok($flag, 'No files are in both MANIFEST and MANIFEST.SKIP');

  return;
}


1;

__END__