Test::F...hareDir(3)

✨ NAME ✨

okay so bestie, this is the Test::File::ShareDir(3) page — and it’s literally Test::File::ShareDir: Create a Fake ShareDir for your modules for testing. That’s the whole name, no cap. 🎀

🦋 VERSION 🦋

This is version 1.001002. Slay.

🌸 SYNOPSIS 🌸

Here’s the vibe:

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 💖

okay so Test::File::ShareDir is some lowkey low-level plumbing that lets a distribution perform tests while it consumes its own "share" directories in a manner similar to how they’ll be once installed. Basically File::ShareDir gets 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. periodt.

🌈 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. iconic.

🧚 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. choose your fighter 🙈

🎀 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 <cpan:///author/dolmen>
• ETHER <cpan:///author/ether>
• HAARG <cpan:///author/haarg>
• RJBS <cpan:///author/rjbs>

🌸 AUTHOR 🌸

Kent Fredric <kentnl@cpan.org> — the icon, the legend. 👑

🎀 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.

mwah 💋 — brought to you by perl v5.42.0, dated 2017-03-03, with the footer title Test::F...hareDir(3) doing its little truncated thing. that’s the tea. ☕