How to specify tests dependencies with Makefile.PL?

[OlegG]

Yesterday I uploaded my new module to CPAN. It has some specific test dependency: Test::Mock::LWP::Dispatch. Today I got 17 failed reports from CPAN Testers. All has "Can't locate Test/Mock/LWP/Dispatch.pm in @INC ...". Example.
So, how to specify test dependencies properly? Now my Makefile.PL looks likes this:

WriteMakefile(
    NAME              => 'LWP::UserAgent::Cached',
    LICENSE           => 'perl',
    VERSION_FROM      => 'lib/LWP/UserAgent/Cached.pm', # finds $VERSI
+ON
    PREREQ_PM         => { 'LWP::UserAgent' => 0 }, # e.g., Module::Na
+me => 1.1
    META_MERGE        => { 
    resources => {repository => 'https://github.com/olegwtf/p5-LWP-Use
+rAgent-Cached'},
    test_requires => {
        'Test::More' => 0.88,
        'Test::Mock::LWP::Dispatch' => 0.02,
        'File::Temp' => 0
    }
     },
    ($] >= 5.005 ?     ## Add these new keywords supported since 5.005
      (ABSTRACT_FROM  => 'lib/LWP/UserAgent/Cached.pm', # retrieve abs
+tract from module
       AUTHOR         => 'Oleg G <[e-mail]>') : ()),
);

But it seems that `test_requires' option doesn't work.

[davido]

The snippet you showed from your Makefile.PL suggests you're using ExtUtils::MakeMaker. EU::MM provides several hooks that enable you to specify module dependencies for different stages in your module's life.

If you have a dependency that has to be installed before Makefile.PL can run on the target system, you specify it as a CONFIGURE_REQUIRES option. An example of such a need is Math::Prime::FastSieve, where Inline::MakeMaker has to be installed on the target system, as well as a relatively recent version of EU::MM before the target system runs Makefile.PL.

By listing those types of dependencies in a CONFIGURE_REQUIRES parameter, the module author, upon building the distribution tells EU::MM to place a configure_requires section in META.yml and META.json. META.yml is used by the cpan shell (as well as the other common install tools) to determine the dependencies. The cpan shell will see that the CONFIGURE_REQUIRES dependency is there, and will install it before invoking Makefile.PL. CONFIGURE_REQUIRES doesn't affect the makefile, it affects what modules are available to Makefile.PL.

Ok, that's CONFIGURE_REQUIRES. That's not the stage you need to affect. I just mention it as an example. You need to have a dependency in place before the tests are run. There is no TEST_REQUIRES parameter. But there is a BUILD_REQUIRES, which will get the dependency installed in time for the build process. Technically your module is already built before it's tested, but that detail isn't as important.

Of course PREREQ_PM is the final opportunity to list dependencies, but that isn't what you need here, as that parameter is intended to get a module dependency installed, not a testing/building dependency.

My own experience in this area is partially documented in the thread that someone else already identified here: Clean smoke-test install for Inline based modules using Inline::MakeMaker

Just keep in mind the following:

1. perl Makefile.PL: If you need something installed before this stage, and it's not needed by the module itself, use CONFIG_REQUIRES. This depends on a fairly recent version of EU::MM, so may want to also specify a minimum EU::MM version in your CONFIG_REQUIRES (else target systems will get some non-fatal warnings when the old EU::MM doesn't know what to do with this param -- not important but maybe confusing to users).
2. make and make test: If you need something installed before this stage, but again it's not needed by the module itself, use BUILD_REQUIRES This also requires a fairly recent version of EU::MM, so if you use BUILD_REQUIRES, you may want to list a minimum version of EU::MM in a CONFIG_REQUIRES section (else the target user will get some non-fatal warnings upon running perl Makefile.PL -- again, not important but maybe confusing to users).
3. make install: If you need something installed for the module itself to function properly, use PREREQ_PM This option has been around quite awhile, so you don't really need to worry about minimum EU::MM version numbers.

As usual, I'm sure if I've misstated something or left something out another helpful individual here will fill in those blanks. :)

[OlegG]

Thank you for such detailed answer. I will try it now.
But can you explain, will cpan shell install dependencies listed in BUILD_REQUIRES if user typed "notest install XX::YY"?

[davido]

It certainly should. As I mentioned in my post above, BUILD_REQUIRES isn't specifically for the testing phase. It's for the build phase, which is actually earlier than the test phase. It's the place to list build dependencies, but happens to also be a good place for listing test dependencies. The reason I say it's a good place is this: It's my opinion (and only my opinion) that PREREQ_PM should be reserved for your module's actual dependencies. CONFIGURE_REQUIRES should be reserved for Makefile.PL's dependencies. BUILD_REQUIRES should be used for anything that is essential to the 'make' process or the make test process, but that is not essential for the target module itself once it's installed.

These aren't the only hooks either. There are additional hooks for installing executables, and other paraphernalia. But when it comes to dependencies that are themselves actually modules, these are the three points of interest.

[Anonymous Monk]

But it seems that `test_requires' option doesn't work.

What test_requires option; where is that documented?

See Clean smoke-test install for Inline based modules using Inline::MakeMaker

[OlegG]

>What test_requires option; where is that documented?

I found it on perlmonks :)

[jhourcle]

With it being in META_MERGE, it's a sign that it's just there to be used by some other module that reads the meta files. The only module that I know of that uses test_requires is Module::Install, but I've never actually used it, so I don't know all of its intricacies (eg, if you need to hide stuff in META_MERGE)

Of course, if you dig through the Module::Install::API documentation, you'll find the following notes:

As of this writing, test_requires is just an alias for build_requires, but this may change in the future.

The values set by build_requires and test_requires are passed to ExtUtils::MakeMaker as a BUILD_REQUIRES attribute, which may fall back to PREREQ_PM if your ExtUtils::MakeMaker is not new enough.