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

VERSION
   Version 0.021

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
   <https://en.wikipedia.org/wiki/Google_Test#Small_Tests_(Unit_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;

       use Test::MockFile;

       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";

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.
       Test::MockFile->file("/bar", "...");
       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"

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.

   See "Mock Stats" for what goes in this hash ref.

 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 in this hash ref.

 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, \@contents, $stats)

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

   @contents should be provided in the sort order you expect to see the
   files from readdir. NOTE: Because "." and ".." will always be the first
   things readdir returns, These files are automatically inserted at the
   front of the array.

   See "Mock Stats" for what goes in this hash ref.

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

       Test::MockFile->file( $file, $contents, {
               'dev'       => 0,        # stat[0]
               'inode'     => 0,        # stat[1]
               'mode'      => $mode,    # stat[2]
               'nlink'     => 0,        # stat[3]
               'uid'       => 0,        # stat[4]
               'gid'       => 0,        # 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.

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

       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.

 contents
   Optional Arg: $contents

   Reports or updates the current contents of the file.

   To update, pass an array ref of strings for a dir or a string for a
   file. Symlinks have no contents.

 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
   <http://perldoc.perl.org/functions/stat.html>, lstat
   <http://perldoc.perl.org/functions/lstat.html> and -X operators
   <http://perldoc.perl.org/functions/-X.html>. 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

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
   Copyright 2018 cPanel L.L.C.

   All rights reserved.

   <http://cpanel.net>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.