NAME

Test::File::ShareDir - Create a Fake ShareDir for your modules for testing.

VERSION

version 1.001003

SYNOPSIS

use Test::More;

# use FindBin; optional

use Test::File::ShareDir
    # -root => "$FindBin::Bin/../" # optional,
    -share => {
        -module => { 'My::Module' => 'share/MyModule' }
        -dist   => { 'My-Dist'    => 'share/somefolder' }
    };

use My::Module;

use File::ShareDir qw( module_dir dist_dir );

module_dir( 'My::Module' ) # dir with files from $dist/share/MyModule

dist_dir( 'My-Dist' ) # dir with files from $dist/share/somefolder

DESCRIPTION

Test::File::ShareDir is some low level plumbing to enable a distribution to perform tests while consuming its own share directories in a manner similar to how they will be once installed.

This allows File::ShareDir to see the latest version of content instead of simply whatever is installed on whichever target system you happen to be testing on.

Note: This module only has support for creating 'new' style share dirs and are NOT compatible with old File::ShareDirs.

For this reason, unless you have File::ShareDir 1.00 or later installed, this module will not be usable by you.

SIMPLE INTERFACE

Starting with version 0.4.0, there are a few extra interfaces you can use.

These will probably be more useful, and easier to grok, because they don't have a layer of indirection in order to simultaneously support both Module and Dist ShareDir's.

Simple Exporter Interfaces

Test::File::ShareDir::Dist

Test::File::ShareDir::Dist provides a simple export interface for making TempDir ShareDir's from a given path:

use Test::File::ShareDir::Dist { "Dist-Name" => "share/" };

This will automatically create a ShareDir for Dist-Name in a TempDir based on the contents of CWD/share/

See Test::File::ShareDir::Dist for details.

Test::File::ShareDir::Module

Test::File::ShareDir::Module provides a simple export interface for making TempDir ShareDir's from a given path:

use Test::File::ShareDir::Module { "Module::Name" => "share/" };

This will automatically create a ShareDir for Module::Name in a TempDir based on the contents of CWD/share/

See Test::File::ShareDir::Module for details.

Simple Object Oriented Interfaces

Test::File::ShareDir::Object::Dist

Test::File::ShareDir::Object::Dist provides a simple object oriented interface for making TempDir ShareDir's from a given path:

use Test::File::ShareDir::Object::Dist;

my $obj = Test::File::ShareDir::Object::Dist->new( dists => { "Dist-Name" => "share/" } );
$obj->install_all_dists;
$obj->register;

This will automatically create a ShareDir for Dist-Name in a TempDir based on the contents of CWD/share/

See Test::File::ShareDir::Object::Dist for details.

Test::File::ShareDir::Object::Module

Test::File::ShareDir::Object::Module provides a simple object oriented interface for making TempDir ShareDir's from a given path:

use Test::File::ShareDir::Object::Module;

my $obj = Test::File::ShareDir::Object::Module->new( modules => { "Module::Name" => "share/" } );
$obj->install_all_modules;
$obj->register;

This will automatically create a ShareDir for Module::Name in a TempDir based on the contents of CWD/share/

See Test::File::ShareDir::Object::Module for details.

SCOPE LIMITED UTILITIES

Test::File::ShareDir provides a few utility functions to aide in temporarily adjusting ShareDir behavior.

use Test::File::ShareDir qw( with_dist_dir with_module_dir );

with_dist_dir({ 'Dist-Name' => 'Some/Path' }, sub {
  # dist_dir() now behaves differently here
});
with_module_dir({ 'Module::Name' => 'Some/Path' }, sub {
  # module_dir() now behaves differently here
});

See EXPORTABLE FUNCTIONS for details.

IMPORTING

Since 1.001000, there are 2 ways of passing arguments to import

use Foo { -root => ... options }, qw( functions to import );
use Foo -optname => option, -optname => option, qw( functions to import );

Both should work, but the former might be less prone to accidental issues.

IMPORT OPTIONS

-root

This parameter is the prefix the other paths are relative to.

If this parameter is not specified, it defaults to the Current Working Directory ( CWD ).

In versions prior to 0.3.0, this value was mandatory.

The rationale behind using CWD as the default value is as follows.

• Most users of this module are likely to be using it to test distributions
• Most users of this module will be using it in $project/t/ to load files from $project/share/
• Most CPAN tools run tests with CWD = $project

Therefor, defaulting to CWD is a reasonably sane default for most people, but where it is not it can still be overridden.

-root => "$FindBin::Bin/../" # resolves to project root from t/ regardless of Cwd.

-share

This parameter is mandatory, and contains a hashref containing the data that explains what directories you want shared.

-share =>  { ..... }

-module

-module contains a hashref mapping Module names to path names for module_dir style share dirs.

-share => {
  -module => { 'My::Module' => 'share/mymodule/', }
}

...

module_dir('My::Module')

Notedly, it is a hashref, which means there is a limitation of one share dir per module. This is simply because having more than one share dir per module makes no sense at all.

-dist

-dist contains a hashref mapping Distribution names to path names for dist_dir style share dirs. The same limitation applied to -module applies here.

-share => {
  -dist => { 'My-Dist' => 'share/mydist' }
}
...
dist_dir('My-Dist')

EXPORTABLE FUNCTIONS

with_dist_dir

Sets up a ShareDir environment with limited context.

# with_dist_dir(\%config, \&sub);
with_dist_dir( { 'Dist-Name' => 'share/' } => sub {

    # File::ShareDir resolves to a copy of share/ in this context.

} );

%config can contain anything Test::File::ShareDir::Dist accepts.

• -root: Defaults to $CWD
• _$distName_: Declare $distName's ShareDir.

Since 1.001000

with_module_dir

Sets up a ShareDir environment with limited context.

# with_module_dir(\%config, \&sub);
with_module_dir( { 'Module::Name' => 'share/' } => sub {

    # File::ShareDir resolves to a copy of share/ in this context.

} );

%config can contain anything Test::File::ShareDir::Module accepts.

• -root: Defaults to $CWD
• _$moduleName_: Declare $moduleName's ShareDir.

Since 1.001000

THANKS

Thanks to the #distzilla crew for ideas,suggestions, code review and debugging, even though not all of it made it into releases.

• DOLMEN
• ETHER
• HAARG
• RJBS

AUTHOR

Kent Fredric kentnl@cpan.org

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric kentnl@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.