Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kentnl/test-file-sharedir

Create a Fake ShareDir for your modules for testing
https://github.com/kentnl/test-file-sharedir
perl
Last synced: about 1 month ago
JSON representation
Create a Fake ShareDir for your modules for testing
Host: GitHub
URL: https://github.com/kentnl/test-file-sharedir
Owner: kentnl
License: other
Created: 2011-02-21T11:49:53.000Z (almost 14 years ago)
Default Branch: master
Last Pushed: 2017-03-01T11:39:15.000Z (almost 8 years ago)
Last Synced: 2024-06-18T16:49:01.772Z (6 months ago)
Topics: perl
Language: Perl
Size: 479 KB
Stars: 3
Watchers: 2
Forks: 2
Open Issues: 2
Metadata Files:
- Readme: README.mkdn
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project

README

        # 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`](https://metacpan.org/pod/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`](https://metacpan.org/pod/Test::File::ShareDir::Dist) for details.

### `Test::File::ShareDir::Module`

[`Test::File::ShareDir::Module`](https://metacpan.org/pod/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`](https://metacpan.org/pod/Test::File::ShareDir::Module) for details.

## Simple Object Oriented Interfaces

### `Test::File::ShareDir::Object::Dist`

[`Test::File::ShareDir::Object::Dist`](https://metacpan.org/pod/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`](https://metacpan.org/pod/Test::File::ShareDir::Object::Dist) for details.

### `Test::File::ShareDir::Object::Module`

[`Test::File::ShareDir::Object::Module`](https://metacpan.org/pod/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`](https://metacpan.org/pod/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`](#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`](https://metacpan.org/pod/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`](https://metacpan.org/pod/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 

# COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric .

This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.