NAME

Test::CPANpm - Test a distribution's interaction with CPAN before uploading.

SYNOPSIS

  use Test::CPANpm;
  use Test::More qw(no_plan);
  
  cpan_depends_ok(
    ['CGI', 'Module::Build', 'Acme::Wabbit'],
    'got the right dependancies'
  );

  cpan_depends_ok_force_missing(
    ['Some::Module::Build::Subclass', 'CGI', 'Module::Build', 'Acme::Wabbit'],
    ['Some::Module::Build::Subclass'],
    'got dependancies even though our Module::Build subclass is missing'
  );
  

DESCRIPTION

Test::CPANpm fools CPAN.pm into thinking it has downloaded and unpacked your package, then has it attempt to generate a Makefile or Build script. After this process completes, it asks your CPAN module what dependancies it thinks exist.

If you just want to make sure your distribution is packaged in a way that is good for CPAN, consider using Test::Distribution instead. The main time that Test::CPANpm is useful is when you depend on modules inside your Makefile.PL or Build.PL script and you want to make sure that you degrade gracefully if those modules are not available.

TESTS

cpan_depends_ok([modules], $test_name)

Generate a distribution directory and tell CPAN to process it. The test will pass if your distribution depends on the exact modules listed in [modules].

cpan_depends_ok_force_missing([modules], [force-missing], $test_name)

Create a bunch of modules that will fail to load, named in the [force-missing] array. Preprend this to our @INC, then do the cpan_depends_ok() test above. This is useful if, say, you have a Module::Build subclass, and you want to verify that your Build.PL script whines about this subclass missing in a way that CPAN can understand.

The reason the fake modules are generated, is to prevent the already-installed modules on your system from interfereing with this test.

Example: Given a Build.PL that contains the following:

  my $build;

  our %opts = (
      module_name         =>  'My::Module::Subclass',
      license             =>  'perl',
      requires            =>  {
          'Test::CPANpm'                    =>  '0',
          # My::Module provides My::Module::Build
          'My::Module'                    =>  '0',
      },
      create_makefile_pl  =>  'passthrough',
  );

  eval { require My::Module::Build; };

  if($@) {
    warn "My::Module::Build is required to build this module!";
    $opts{requires}{'My::Module::Build'} = 0;
    # setting installdirs to an empty hash makes "./Build install" fail,
    # but we'll still get a "Build" script/Makefile that CPAN can use to
    # find prereqs
    $build = Module::Build->new(%opts, installdirs => {});
  } else {
    $build = My::Module::Build->new(%opts);
  }

  $build->create_build_script;

The following tests would be expected to pass:

  cpan_depends_ok(
    ['My::Module', 'Test::CPANpm'],
    'CPAN sees basic dependancies'
  );
  
  cpan_depends_ok_force_missing(
    [
        'My::Module', 'Test::CPANpm', 'My::Module::Build'
    ],
    [
        'My::Module::Build'
    ],
    'CPAN complains if My::Module::Build is missing'
  );

CAVEAT

You must have a Makefile or Build script in the current working directory for Test::CPANpm to work. It will call the "distdir" command on that script in order to build it's test environment. (This also means that your MANIFEST needs to be up-to-date for the tests to usually pass... but of course your MANIFEST needs to be up-to-date before you can upload to CPAN anyway, right?)

TODO

I'm rushing this package out because I have another package whose testability depends on these functions, but there's more I'd like to see in here:

Test that you depend on particular versions of modules
Test that a "Makefile" is actually created

This is tacitly, implicitly done already by cpan_depends_ok, since you won't get any dependancy information out of CPAN without a Makefile, but an explicit test would still be good.

Only generate distdir once for multiple tests
Check that the modules you depend on actually are on CPAN

Right now we just test that you depend on certain modules, there is no check to see if they are actually available.

Tests that use CPANPLUS

CPANPLUS is supposed to behave more-or-less the same as CPAN given a distribution, but it'd be nice to prove it.

SEE ALSO

Test::Distribution, CPAN, ExtUtils::MakeMaker, Module::Build, Module::Depends

AUTHOR

Tyler "Crackerjack" MacDonald <japh@crackerjack.net>

LICENSE

Copyright 2006 Tyler MacDonald.

This is free software; you may redistribute it under the same terms as perl itself.