---
name: "Test::File::ShareDir"
section: "3pm"
platform: "linux"
package: "libtest-file-sharedir-perl"
version: "1.001002-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::File::ShareDir"
---

# Test::File::ShareDir(3pm)

Create a Fake ShareDir for your modules for testing.

## NAME

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

## VERSION

version 1.001002

## 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 \<cpan:///author/dolmen\>

- •

  ETHER \<cpan:///author/ether\>

- •

  HAARG \<cpan:///author/haarg\>

- •

  RJBS \<cpan:///author/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.