NAME

Test::MockFile - Allows tests to validate code that can interact with files without touching the file system.

VERSION

Version 0.026

SYNOPSIS

Intercepts file system calls for specific files so unit testing can take place without any files being altered on disk.

This is useful for small tests where file interaction is discouraged.

A strict mode is even provided which can throw a die when files are accessed during your tests!

# Loaded before Test::MockFile so uses the core perl functions without any hooks.
use Module::I::Dont::Want::To::Alter;

# strict mode
use Test::MockFile qw< strict >;

# Be sure to assign the output of mocks, they disappear when they go out of scope
my $mock_file = Test::MockFile->file("/foo/bar", "contents\ngo\nhere");
open my $fh, '<', '/foo/bar' or die; # Does not actually open the file on disk
say 'ok' if -e $fh;
close $fh;
say 'ok' if -f '/foo/bar';
say '/foo/bar is THIS BIG: ' . -s '/foo/bar';

my $missing_mocked_file = Test::MockFile->file('/foo/baz'); # File starts out missing
my $opened              = open my $baz_fh, '<', '/foo/baz'; # File reports as missing so fails
say 'ok' if !-e '/foo/baz';

open $baz_fh, '>', '/foo/baz' or die; # open for writing
print {$baz_fh} "replace contents\n";

open $baz_fh, '>>', '/foo/baz' or die; # open for append.
print {$baz_fh} "second line";
close $baz_fh;

say $baz->contents;

# Unmock your file.
undef $missing_mocked_file;

# The file check will now happen on file system now the file is no longer mocked.
say 'ok' if !-e '/foo/baz';

my $quux    = Test::MockFile->file('/foo/bar/quux.txt');
my @matches = </foo/bar/*.txt>;       # ( 'quux.txt' )
my @matches = glob('/foo/bar/*.txt'); # same as above

IMPORT

If the module is loaded in strict mode, any file checks, open, sysopen, opendir, stat, or lstat will throw a die.

For example:

use Test::MockFile qw< strict >;

# This will not die.
my $file    = Test::MockFile->file("/bar", "...");
my $symlink = Test::MockFile->symlink("/foo", "/bar");
-l '/foo' or print "ok\n";
open my $fh, '>', '/foo';

# All of these will die
open my $fh, '>', '/unmocked/file'; # Dies
sysopen my $fh, '/other/file', O_RDONLY;
opendir my $fh, '/dir';
-e '/file';
-l '/file';

Relative paths are not supported:

use Test::MockFile;

# Checking relative vs absolute paths
$file = Test::MockFile->file( '/foo/../bar', '...' ); # not ok - relative path
$file = Test::MockFile->file( '/bar',        '...' ); # ok     - absolute path
$file = Test::MockFile->file( 'bar', '...' );         # ok     - current dir

And if you have multiple forward slashes, it will confess as well:

use Test::MockFile;
$file = Test::MockFile->file( '//bar', '...' );

SUBROUTINES/METHODS

file

Args: ($file, $contents, $stats)

This will make cause $file to be mocked in all file checks, opens, etc.

undef contents means that the file should act like it's not there. You can only set the stats if you provide content.

If you give file content, the directory inside it will be mocked as well.

my $f = Test::MockFile->file( '/foo/bar' );
-d '/foo' # not ok

my $f = Test::MockFile->file( '/foo/bar', 'some content' );
-d '/foo' # ok

See "Mock Stats" for what goes into the stats hashref.

file_from_disk

Args: ($file_to_mock, $file_on_disk, $stats)

This will make cause $file to be mocked in all file checks, opens, etc.

If file_on_disk isn't present, then this will die.

See "Mock Stats" for what goes into the stats hashref.

symlink

Args: ($readlink, $file )

This will cause $file to be mocked in all file checks, opens, etc.

$readlink indicates what "fake" file it points to. If the file $readlink points to is not mocked, it will act like a broken link, regardless of what's on disk.

If $readlink is undef, then the symlink is mocked but not present.(lstat $file is empty.)

Stats are not able to be specified on instantiation but can in theory be altered after the object is created. People don't normally mess with the permissions on a symlink.

dir

Args: ($dir)

This will cause $dir to be mocked in all file checks, and opendir interactions.

The directory name is normalized so any trailing slash is removed.

$dir = Test::MockFile->dir( 'mydir/', ... ); # ok
$dir->path();                                # mydir

If there were previously mocked files (within the same scope), the directory will exist. Otherwise, the directory will be nonexistent.

my $dir = Test::MockFile->dir('/etc');
-d $dir;          # not ok since directory wasn't created yet
$dir->contents(); # undef

# Now we can create an empty directory
mkdir '/etc';
$dir_etc->contents(); # . ..

# Alternatively, we can already create files with ->file()
$dir_log  = Test::MockFile->dir('/var');
$file_log = Test::MockFile->file( '/var/log/access_log', $some_content );
$dir_log->contents(); # . .. access_log

# If you create a nonexistent file but then give it content, it will create
# the directory for you
my $file = Test::MockFile->file('/foo/bar');
my $dir  = Test::MockFile->dir('/foo');
-d '/foo'                 # false
-e '/foo/bar';            # false
$dir->contents();         # undef

$file->contents('hello');
-e '/foo/bar';            # true
-d '/foo';                # true
$dir->contents();         # . .. bar

NOTE: Because . and .. will always be the first things readdir returns, These files are automatically inserted at the front of the array. The order of files is sorted.

If you want to affect the stat information of a directory, you need to use the available core Perl keywords. (We might introduce a special helper method for it in the future.)

$d = Test::MockFile->dir( '/foo', [], { 'mode' => 0755 } );    # dies
$d = Test::MockFile->dir( '/foo', undef, { 'mode' => 0755 } ); # dies

$d = Test::MockFile->dir('/foo');
mkdir $d, 0755;                   # ok

Mock Stats

When creating mocked files or directories, we default their stats to:

my $attrs = Test::MockFile->file( $file, $contents, {
        'dev'       => 0,        # stat[0]
        'inode'     => 0,        # stat[1]
        'mode'      => $mode,    # stat[2]
        'nlink'     => 0,        # stat[3]
        'uid'       => int $>,   # stat[4]
        'gid'       => int $),   # stat[5]
        'rdev'      => 0,        # stat[6]
        'atime'     => $now,     # stat[8]
        'mtime'     => $now,     # stat[9]
        'ctime'     => $now,     # stat[10]
        'blksize'   => 4096,     # stat[11]
        'fileno'    => undef,    # fileno()
} );

You'll notice that mode, size, and blocks have been left out of this. Mode is set to 666 (for files) or 777 (for directories), xored against the current umask. Size and blocks are calculated based on the size of 'contents' a.k.a. the fake file.

When you want to override one of the defaults, all you need to do is specify that when you declare the file or directory. The rest will continue to default.

my $mfile = Test::MockFile->file("/root/abc", "...", {inode => 65, uid => 123, mtime => int((2000-1970) * 365.25 * 24 * 60 * 60 }));

my $mdir = Test::MockFile->dir("/sbin", "...", { mode => 0700 }));

new

This class method is called by file/symlink/dir. There is no good reason to call this directly.

Optional Arg: $contents

Retrieves or updates the current contents of the file.

Only retrieves the content of the directory (as an arrayref). You can set directory contents with calling the file() method described above.

Symlinks have no contents.

filename

Deprecated. Same as path.

path

The path (filename or dirname) of the file or directory this mock object is controlling.

unlink

Makes the virtual file go away. NOTE: This also works for directories.

touch

Optional Args: ($epoch_time)

This function acts like the UNIX utility touch. It sets atime, mtime, ctime to $epoch_time.

If no arguments are passed, $epoch_time is set to time(). If the file does not exist, contents are set to an empty string.

stat

Returns the stat of a mocked file (does not follow symlinks.)

readlink

Optional Arg: $readlink

Returns the stat of a mocked file (does not follow symlinks.) You can also use this to change what your symlink is pointing to.

is_link

returns true/false, depending on whether this object is a symlink.

is_dir

returns true/false, depending on whether this object is a directory.

is_file

returns true/false, depending on whether this object is a regular file.

size

returns the size of the file based on its contents.

exists

returns true or false based on if the file exists right now.

blocks

Calculates the block count of the file based on its size.

chmod

Optional Arg: $perms

Allows you to alter the permissions of a file. This only allows you to change the 07777 bits of the file permissions. The number passed should be the octal 0755 form, not the alphabetic "755" form

permissions

Returns the permissions of the file.

mtime

Optional Arg: $new_epoch_time

Returns and optionally sets the mtime of the file if passed as an integer.

ctime

Optional Arg: $new_epoch_time

Returns and optionally sets the ctime of the file if passed as an integer.

atime

Optional Arg: $new_epoch_time

Returns and optionally sets the atime of the file if passed as an integer.

add_file_access_hook

Args: ( $code_ref )

You can use add_file_access_hook to add a code ref that gets called every time a real file (not mocked) operation happens. We use this for strict mode to die if we detect your program is unexpectedly accessing files. You are welcome to use it for whatever you like.

Whenever the code ref is called, we pass 2 arguments: $code->($access_type, $at_under_ref). Be aware that altering the variables in $at_under_ref will affect the variables passed to open / sysopen, etc.

One use might be:

Test::MockFile::add_file_access_hook(sub { my $type = shift; print "$type called at: " . Carp::longmess() } );

clear_file_access_hooks

Calling this subroutine will clear everything that was passed to add_file_access_hook

How this mocking is done:

Test::MockFile uses 2 methods to mock file access:

-X via Overload::FileCheck

It is currently not possible in pure perl to override stat, lstat and -X operators. In conjunction with this module, we've developed Overload::FileCheck.

This enables us to intercept calls to stat, lstat and -X operators (like -e, -f, -d, -s, etc.) and pass them to our control. If the file is currently being mocked, we return the stat (or lstat) information on the file to be used to determine the answer to whatever check was made. This even works for things like -e _. If we do not control the file in question, we return FALLBACK_TO_REAL_OP() which then makes a normal check.

CORE::GLOBAL:: overrides

Since 5.10, it has been possible to override function calls by defining them. like:

*CORE::GLOBAL::open = sub(*;$@) {...}

Any code which is loaded AFTER this happens will use the alternate open. This means you can place your use Test::MockFile statement after statements you don't want to be mocked and there is no risk that the code will ever be altered by Test::MockFile.

We oveload the following statements and then return tied handles to enable the rest of the IO functions to work properly. Only open / sysopen are needed to address file operations. However opendir file handles were never setup for tie so we have to override all of opendir's related functions.

open
sysopen
opendir
readdir
telldir
seekdir
rewinddir
closedir

BAREWORD FILEHANDLE FAILURES

There is a particular type of bareword filehandle failures that cannot be fixed.

These errors occur because there's compile-time code that uses bareword filehandles in a function call that cannot be expressed by this module's prototypes for core functions.

The only solution to these is loading `Test::MockFile` after the other code:

This will fail:

# This will fail because Test2::V0 will eventually load Term::Table::Util
# which calls open() with a bareword filehandle that is misparsed by this module's
# opendir prototypes
use Test::MockFile ();
use Test2::V0;

This will succeed:

# This will succeed because open() will be parsed by perl
# and only then we override those functions
use Test2::V0;
use Test::MockFile ();

(Using strict-mode will not fix it, even though you should use it.)

AUTHOR

Todd Rinaldo, <toddr at cpan.org>

BUGS

Please report any bugs or feature requests to https://github.com/CpanelInc/Test-MockFile.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Test::MockFile

You can also look for information at:

CPAN Ratings

https://cpanratings.perl.org/d/Test-MockFile
Search CPAN

https://metacpan.org/release/Test-MockFile

ACKNOWLEDGEMENTS

Thanks to Nicolas R., <atoomic at cpan.org> for help with Overload::FileCheck. This module could not have been completed without it.

LICENSE AND COPYRIGHT

http://cpanel.net

This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

To install Test::MockFile, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::MockFile

CPAN shell

perl -MCPAN -e shell
install Test::MockFile

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

IMPORT

SUBROUTINES/METHODS

file

file_from_disk

symlink

dir

Mock Stats

new

contents

filename

path

unlink

touch

stat

readlink

is_link

is_dir

is_file

size

exists

blocks

chmod

permissions

mtime

ctime

atime

add_file_access_hook

clear_file_access_hooks

How this mocking is done:

-X via Overload::FileCheck

CORE::GLOBAL:: overrides

BAREWORD FILEHANDLE FAILURES

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Module Install Instructions