Test::File::ShareDir − Create a Fake ShareDir for your modules for testing.
version 1.001002
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"
"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.
"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.
"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.
−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')
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
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 to the "#distzilla" crew for ideas,suggestions, code review and debugging, even though not all of it made it into releases.
|
• |
DOLMEN <cpan:///author/dolmen> |
|||
|
• |
ETHER <cpan:///author/ether> |
|||
|
• |
HAARG <cpan:///author/haarg> |
|||
|
• |
RJBS <cpan:///author/rjbs> |
Kent Fredric <[email protected]>
This software is copyright (c) 2017 by Kent Fredric <[email protected]>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.