Test::File::ShareDir - Create a Fake ShareDir for your modules for testing.
version 1.001003
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
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.
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.
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 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.
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 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.
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.
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.
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
CPANtools run tests withCWD= $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.
This parameter is mandatory, and contains a hashref containing the data that explains what directories you want shared.
-share => { ..... }
-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 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')
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'sShareDir.
Since 1.001000
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'sShareDir.
Since 1.001000
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
Kent Fredric kentnl@cpan.org
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.