.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::MockFile 3pm" .TH Test::MockFile 3pm "2023-02-04" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::MockFile \- Allows tests to validate code that can interact with files without touching the file system. .SH "VERSION" .IX Header "VERSION" Version 0.035 .SH "SYNOPSIS" .IX Header "SYNOPSIS" Intercepts file system calls for specific files so unit testing can take place without any files being altered on disk. .PP This is useful for small tests where file interaction is discouraged. .PP A strict mode is even provided (and turned on by default) which can throw a die when files are accessed during your tests! .PP .Vb 2 \& # Loaded before Test::MockFile so uses the core perl functions without any hooks. \& use Module::I::Dont::Want::To::Alter; \& \& # strict mode by default \& use Test::MockFile (); \& \& # non\-strict mode \& use Test::MockFile qw< nostrict >; \& \& # Load with one or more plugins \& \& use Test::MockFile plugin => \*(AqFileTemp\*(Aq; \& use Test::MockFile plugin => [ \*(AqFileTemp\*(Aq, ... ]; \& \& # Be sure to assign the output of mocks, they disappear when they go out of scope \& my $foobar = Test::MockFile\->file( "/foo/bar", "contents\engo\enhere" ); \& open my $fh, \*(Aq<\*(Aq, \*(Aq/foo/bar\*(Aq or die; # Does not actually open the file on disk \& say \*(Aq/foo/bar exists\*(Aq if \-e $fh; \& close $fh; \& \& say \*(Aq/foo/bar is a file\*(Aq if \-f \*(Aq/foo/bar\*(Aq; \& say \*(Aq/foo/bar is THIS BIG: \*(Aq . \-s \*(Aq/foo/bar\*(Aq; \& \& my $foobaz = Test::MockFile\->file(\*(Aq/foo/baz\*(Aq); # File starts out missing \& my $opened = open my $baz_fh, \*(Aq<\*(Aq, \*(Aq/foo/baz\*(Aq; # File reports as missing so fails \& say \*(Aq/foo/baz does not exist yet\*(Aq if !\-e \*(Aq/foo/baz\*(Aq; \& \& open $baz_fh, \*(Aq>\*(Aq, \*(Aq/foo/baz\*(Aq or die; # open for writing \& print {$baz_fh} "first line\en"; \& \& open $baz_fh, \*(Aq>>\*(Aq, \*(Aq/foo/baz\*(Aq or die; # open for append. \& print {$baz_fh} "second line"; \& close $baz_fh; \& \& say "Contents of /foo/baz:\en>>" . $foobaz\->contents() . \*(Aq<<\*(Aq; \& \& # Unmock your file. \& # (same as the variable going out of scope \& undef $foobaz; \& \& # The file check will now happen on file system now the file is no longer mocked. \& say \*(Aq/foo/baz is missing again (no longer mocked)\*(Aq if !\-e \*(Aq/foo/baz\*(Aq; \& \& my $quux = Test::MockFile\->file( \*(Aq/foo/bar/quux.txt\*(Aq, \*(Aq\*(Aq ); \& my @matches = ; \& \& # ( \*(Aq/foo/bar/quux.txt\*(Aq ) \& say "Contents of /foo/bar directory: " . join "\en", @matches; \& \& @matches = glob(\*(Aq/foo/bar/*.txt\*(Aq); \& \& # same as above \& say "Contents of /foo/bar directory (using glob()): " . join "\en", @matches; .Ve .SH "IMPORT" .IX Header "IMPORT" When the module is loaded with no parameters, strict mode is turned on. Any file checks, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, or \f(CW\*(C`lstat\*(C'\fR will throw a die. .PP For example: .PP .Vb 1 \& use Test::MockFile; \& \& # This will not die. \& my $file = Test::MockFile\->file("/bar", "..."); \& my $symlink = Test::MockFile\->symlink("/foo", "/bar"); \& \-l \*(Aq/foo\*(Aq or print "ok\en"; \& open my $fh, \*(Aq>\*(Aq, \*(Aq/foo\*(Aq; \& \& # All of these will die \& open my $fh, \*(Aq>\*(Aq, \*(Aq/unmocked/file\*(Aq; # Dies \& sysopen my $fh, \*(Aq/other/file\*(Aq, O_RDONLY; \& opendir my $fh, \*(Aq/dir\*(Aq; \& \-e \*(Aq/file\*(Aq; \& \-l \*(Aq/file\*(Aq; .Ve .PP If we want to load the module without strict mode: .PP .Vb 1 \& use Test::MockFile qw< nostrict >; .Ve .PP Relative paths are not supported: .PP .Vb 1 \& use Test::MockFile; \& \& # Checking relative vs absolute paths \& $file = Test::MockFile\->file( \*(Aq/foo/../bar\*(Aq, \*(Aq...\*(Aq ); # not ok \- relative path \& $file = Test::MockFile\->file( \*(Aq/bar\*(Aq, \*(Aq...\*(Aq ); # ok \- absolute path \& $file = Test::MockFile\->file( \*(Aqbar\*(Aq, \*(Aq...\*(Aq ); # ok \- current dir .Ve .ie n .SS "authorized_strict_mode_for_package( $pkg )" .el .SS "authorized_strict_mode_for_package( \f(CW$pkg\fP )" .IX Subsection "authorized_strict_mode_for_package( $pkg )" Add a package namespace to the list of authorize namespaces. .PP .Vb 1 \& authorized_strict_mode_for_package( \*(AqYour::Package\*(Aq ); .Ve .SS "file_arg_position_for_command" .IX Subsection "file_arg_position_for_command" Args: ($command) .PP Provides a hint with the position of the argument most likely holding the file name for the current \f(CW$command\fR call. .PP This is used internaly to provide better error messages. This can be used when plugging hooks to know what's the filename we currently try to access. .ie n .SS "add_strict_rule( $command_rule, $file_rule, $action )" .el .SS "add_strict_rule( \f(CW$command_rule\fP, \f(CW$file_rule\fP, \f(CW$action\fP )" .IX Subsection "add_strict_rule( $command_rule, $file_rule, $action )" Args: ($command_rule, \f(CW$file_rule\fR, \f(CW$action\fR) .PP Add a custom rule to validate strictness mode. This is the fundation to add strict rules. You should use it, when none of the other helper to add rules work for you. .ie n .IP "$command_rule a string or regexp or list of any to indicate which command to match" 4 .el .IP "\f(CW$command_rule\fR a string or regexp or list of any to indicate which command to match" 4 .IX Item "$command_rule a string or regexp or list of any to indicate which command to match" =item\f(CW$file_rule\fR a string or regexp or undef or list of any to indicate which files your rules apply to. .ie n .IP "$action a \s-1CODE\s0 ref or scalar to handle the exception. Returning '1' skip all other rules and indicate an exception." 4 .el .IP "\f(CW$action\fR a \s-1CODE\s0 ref or scalar to handle the exception. Returning '1' skip all other rules and indicate an exception." 4 .IX Item "$action a CODE ref or scalar to handle the exception. Returning '1' skip all other rules and indicate an exception." .PP .Vb 2 \& # Check open() on /this/file \& add_strict_rule( \*(Aqopen\*(Aq, \*(Aq/this/file\*(Aq, sub { ... } ); \& \& # always bypass the strict rule \& add_strict_rule( \*(Aqopen\*(Aq, \*(Aq/this/file\*(Aq, 1 ); \& \& # all available options \& add_strict_rule( \*(Aqopen\*(Aq, \*(Aq/this/file\*(Aq, sub { \& my ($context) = @_; \& \& return; # Skip this rule and continue from the next one \& return 0; # Strict violation, stop testing rules and die \& return 1; # Strict passing, stop testing rules \& } ); \& \& # Disallow open(), close() on everything in /tmp/ \& add_strict_rule( \& [ qw< open close > ], \& qr{^/tmp}xms, \& 0, \& ); \& \& # Disallow open(), close() on everything (ignore filenames) \& # Use add_strict_rule_for_command() instead! \& add_strict_rule( \& [ qw< open close > ], \& undef, \& 0, \& ); .Ve .SS "\fBclear_strict_rules()\fP" .IX Subsection "clear_strict_rules()" Args: none .PP Clear all previously defined rules. (Mainly used for testing purpose) .ie n .SS "add_strict_rule_for_filename( $file_rule, $action )" .el .SS "add_strict_rule_for_filename( \f(CW$file_rule\fP, \f(CW$action\fP )" .IX Subsection "add_strict_rule_for_filename( $file_rule, $action )" Args: ($file_rule, \f(CW$action\fR) .PP Prefer using that helper when trying to add strict rules targeting files. .PP Apply a rule to one or more files. .PP .Vb 1 \& add_strict_rule_for_filename( \*(Aq/that/file\*(Aq => sub { ... } ); \& \& add_strict_rule_for_filename( [ qw{list of files} ] => sub { ... } ); \& \& add_strict_rule_for_filename( qr{*\e.t$} => sub { ... } ); \& \& add_strict_rule_for_filename( [ $dir, qr{^${dir}/} ] => 1 ); .Ve .ie n .SS "add_strict_rule_for_command( $command_rule, $action )" .el .SS "add_strict_rule_for_command( \f(CW$command_rule\fP, \f(CW$action\fP )" .IX Subsection "add_strict_rule_for_command( $command_rule, $action )" Args: ($command_rule, \f(CW$action\fR) .PP Prefer using that helper when trying to add strict rules targeting specici commands. .PP Apply a rule to one or more files. .PP .Vb 1 \& add_strict_rule_for_command( \*(Aqopen\*(Aq => sub { ... } ); \& \& add_strict_rule_for_command( [ qw{open readdir} ] => sub { ... } ); \& \& add_strict_rule_for_command( qr{open.*} => sub { ... } ); \& \& Test::MockFile::add_strict_rule_for_command( \& [qw{ readdir closedir readlink }], \& sub { \& my ($ctx) = @_; \& my $command = $ctx\->{command} // \*(Aqunknown\*(Aq; \& \& warn( "Ignoring strict mode violation for $command" ); \& return 1; \& } \& ); .Ve .ie n .SS "add_strict_rule_generic( $action )" .el .SS "add_strict_rule_generic( \f(CW$action\fP )" .IX Subsection "add_strict_rule_generic( $action )" Args: ($action) .PP Prefer using that helper when adding a rule which is global and does not apply to a specific command or file. .PP Apply a rule to one or more files. .PP .Vb 1 \& add_strict_rule_generic( sub { ... } ); \& \& add_strict_rule_generic( sub { \& my ($ctx) = @_; \& \& my $filename = $ctx\->{filename}; \& \& return unless defined $filename; \& \& return 1 if UNIVERSAL::isa( $filename, \*(AqGLOB\*(Aq ); \& \& return; \& } ); .Ve .SS "is_strict_mode" .IX Subsection "is_strict_mode" Boolean helper to determine if strict mode is currently enabled. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .SS "file" .IX Subsection "file" Args: ($file, \f(CW$contents\fR, \f(CW$stats\fR) .PP This will make cause \f(CW$file\fR to be mocked in all file checks, opens, etc. .PP \&\f(CW\*(C`undef\*(C'\fR contents means that the file should act like it's not there. You can only set the stats if you provide content. .PP If you give file content, the directory inside it will be mocked as well. .PP .Vb 2 \& my $f = Test::MockFile\->file( \*(Aq/foo/bar\*(Aq ); \& \-d \*(Aq/foo\*(Aq # not ok \& \& my $f = Test::MockFile\->file( \*(Aq/foo/bar\*(Aq, \*(Aqsome content\*(Aq ); \& \-d \*(Aq/foo\*(Aq # ok .Ve .PP See \*(L"Mock Stats\*(R" for what goes into the stats hashref. .SS "file_from_disk" .IX Subsection "file_from_disk" Args: \f(CW\*(C`($file_to_mock, $file_on_disk, $stats)\*(C'\fR .PP This will make cause \f(CW$file\fR to be mocked in all file checks, opens, etc. .PP If \f(CW\*(C`file_on_disk\*(C'\fR isn't present, then this will die. .PP See \*(L"Mock Stats\*(R" for what goes into the stats hashref. .SS "symlink" .IX Subsection "symlink" Args: ($readlink, \f(CW$file\fR ) .PP This will cause \f(CW$file\fR to be mocked in all file checks, opens, etc. .PP \&\f(CW$readlink\fR indicates what \*(L"fake\*(R" file it points to. If the file \&\f(CW$readlink\fR points to is not mocked, it will act like a broken link, regardless of what's on disk. .PP If \f(CW$readlink\fR is undef, then the symlink is mocked but not present.(lstat \f(CW$file\fR is empty.) .PP 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. .SS "dir" .IX Subsection "dir" Args: ($dir) .PP This will cause \f(CW$dir\fR to be mocked in all file checks, and \f(CW\*(C`opendir\*(C'\fR interactions. .PP The directory name is normalized so any trailing slash is removed. .PP .Vb 2 \& $dir = Test::MockFile\->dir( \*(Aqmydir/\*(Aq, ... ); # ok \& $dir\->path(); # mydir .Ve .PP If there were previously mocked files (within the same scope), the directory will exist. Otherwise, the directory will be nonexistent. .PP .Vb 3 \& my $dir = Test::MockFile\->dir(\*(Aq/etc\*(Aq); \& \-d $dir; # not ok since directory wasn\*(Aqt created yet \& $dir\->contents(); # undef \& \& # Now we can create an empty directory \& mkdir \*(Aq/etc\*(Aq; \& $dir_etc\->contents(); # . .. \& \& # Alternatively, we can already create files with \->file() \& $dir_log = Test::MockFile\->dir(\*(Aq/var\*(Aq); \& $file_log = Test::MockFile\->file( \*(Aq/var/log/access_log\*(Aq, $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(\*(Aq/foo/bar\*(Aq); \& my $dir = Test::MockFile\->dir(\*(Aq/foo\*(Aq); \& \-d \*(Aq/foo\*(Aq # false \& \-e \*(Aq/foo/bar\*(Aq; # false \& $dir\->contents(); # undef \& \& $file\->contents(\*(Aqhello\*(Aq); \& \-e \*(Aq/foo/bar\*(Aq; # true \& \-d \*(Aq/foo\*(Aq; # true \& $dir\->contents(); # . .. bar .Ve .PP \&\s-1NOTE:\s0 Because \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`..\*(C'\fR will always be the first things \f(CW\*(C`readdir\*(C'\fR returns, These files are automatically inserted at the front of the array. The order of files is sorted. .PP 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.) .PP .Vb 2 \& $d = Test::MockFile\->dir( \*(Aq/foo\*(Aq, [], { \*(Aqmode\*(Aq => 0755 } ); # dies \& $d = Test::MockFile\->dir( \*(Aq/foo\*(Aq, undef, { \*(Aqmode\*(Aq => 0755 } ); # dies \& \& $d = Test::MockFile\->dir(\*(Aq/foo\*(Aq); \& mkdir $d, 0755; # ok .Ve .SS "new_dir" .IX Subsection "new_dir" .Vb 3 \& # short form \& $new_dir = Test::MockFile\->new_dir( \*(Aq/path\*(Aq ); \& $new_dir = Test::MockFile\->new_dir( \*(Aq/path\*(Aq, { \*(Aqmode\*(Aq => 0755 } ); \& \& # longer form 1 \& $dir = Test::MockFile\->dir(\*(Aq/path\*(Aq); \& mkdir $dir\->path(), 0755; \& \& # longer form 2 \& $dir = Test::MockFile\->dir(\*(Aq/path\*(Aq); \& mkdir $dir\->path(); \& chmod $dir\->path(); .Ve .PP This creates a new directory with an optional mode. This is a short-hand that might be removed in the future when a stable, new interface is introduced. .SS "Mock Stats" .IX Subsection "Mock Stats" When creating mocked files or directories, we default their stats to: .PP .Vb 10 \& my $attrs = Test::MockFile\->file( $file, $contents, { \& \*(Aqdev\*(Aq => 0, # stat[0] \& \*(Aqinode\*(Aq => 0, # stat[1] \& \*(Aqmode\*(Aq => $mode, # stat[2] \& \*(Aqnlink\*(Aq => 0, # stat[3] \& \*(Aquid\*(Aq => int $>, # stat[4] \& \*(Aqgid\*(Aq => int $), # stat[5] \& \*(Aqrdev\*(Aq => 0, # stat[6] \& \*(Aqatime\*(Aq => $now, # stat[8] \& \*(Aqmtime\*(Aq => $now, # stat[9] \& \*(Aqctime\*(Aq => $now, # stat[10] \& \*(Aqblksize\*(Aq => 4096, # stat[11] \& \*(Aqfileno\*(Aq => undef, # fileno() \& } ); .Ve .PP 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. .PP 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. .PP .Vb 1 \& 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 })); .Ve .SS "new" .IX Subsection "new" This class method is called by file/symlink/dir. There is no good reason to call this directly. .SS "contents" .IX Subsection "contents" Optional Arg: \f(CW$contents\fR .PP Retrieves or updates the current contents of the file. .PP Only retrieves the content of the directory (as an arrayref). You can set directory contents with calling the \f(CW\*(C`file()\*(C'\fR method described above. .PP Symlinks have no contents. .SS "filename" .IX Subsection "filename" Deprecated. Same as \f(CW\*(C`path\*(C'\fR. .SS "path" .IX Subsection "path" The path (filename or dirname) of the file or directory this mock object is controlling. .SS "unlink" .IX Subsection "unlink" Makes the virtual file go away. \s-1NOTE:\s0 This also works for directories. .SS "touch" .IX Subsection "touch" Optional Args: ($epoch_time) .PP This function acts like the \s-1UNIX\s0 utility touch. It sets atime, mtime, ctime to \f(CW$epoch_time\fR. .PP If no arguments are passed, \f(CW$epoch_time\fR is set to \fBtime()\fR. If the file does not exist, contents are set to an empty string. .SS "stat" .IX Subsection "stat" Returns the stat of a mocked file (does not follow symlinks.) .SS "readlink" .IX Subsection "readlink" Optional Arg: \f(CW$readlink\fR .PP Returns the stat of a mocked file (does not follow symlinks.) You can also use this to change what your symlink is pointing to. .SS "is_link" .IX Subsection "is_link" returns true/false, depending on whether this object is a symlink. .SS "is_dir" .IX Subsection "is_dir" returns true/false, depending on whether this object is a directory. .SS "is_file" .IX Subsection "is_file" returns true/false, depending on whether this object is a regular file. .SS "size" .IX Subsection "size" returns the size of the file based on its contents. .SS "exists" .IX Subsection "exists" returns true or false based on if the file exists right now. .SS "blocks" .IX Subsection "blocks" Calculates the block count of the file based on its size. .SS "chmod" .IX Subsection "chmod" Optional Arg: \f(CW$perms\fR .PP Allows you to alter the permissions of a file. This only allows you to change the \f(CW07777\fR bits of the file permissions. The number passed should be the octal \f(CW0755\fR form, not the alphabetic \f(CW"755"\fR form .SS "permissions" .IX Subsection "permissions" Returns the permissions of the file. .SS "mtime" .IX Subsection "mtime" Optional Arg: \f(CW$new_epoch_time\fR .PP Returns and optionally sets the mtime of the file if passed as an integer. .SS "ctime" .IX Subsection "ctime" Optional Arg: \f(CW$new_epoch_time\fR .PP Returns and optionally sets the ctime of the file if passed as an integer. .SS "atime" .IX Subsection "atime" Optional Arg: \f(CW$new_epoch_time\fR .PP Returns and optionally sets the atime of the file if passed as an integer. .SS "add_file_access_hook" .IX Subsection "add_file_access_hook" Args: ( \f(CW$code_ref\fR ) .PP You can use \fBadd_file_access_hook\fR 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. .PP Whenever the code ref is called, we pass 2 arguments: \&\f(CW\*(C`$code\->($access_type, $at_under_ref)\*(C'\fR. Be aware that altering the variables in \f(CW$at_under_ref\fR will affect the variables passed to open / sysopen, etc. .PP One use might be: .PP .Vb 1 \& Test::MockFile::add_file_access_hook(sub { my $type = shift; print "$type called at: " . Carp::longmess() } ); .Ve .SS "clear_file_access_hooks" .IX Subsection "clear_file_access_hooks" Calling this subroutine will clear everything that was passed to \&\fBadd_file_access_hook\fR .SS "How this mocking is done:" .IX Subsection "How this mocking is done:" Test::MockFile uses 2 methods to mock file access: .PP \fI\-X via Overload::FileCheck\fR .IX Subsection "-X via Overload::FileCheck" .PP 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. .PP 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 \f(CW\*(C`\-e _\*(C'\fR. If we do not control the file in question, we return \f(CW\*(C`FALLBACK_TO_REAL_OP()\*(C'\fR which then makes a normal check. .PP \fI\s-1CORE::GLOBAL::\s0 overrides\fR .IX Subsection "CORE::GLOBAL:: overrides" .PP Since 5.10, it has been possible to override function calls by defining them. like: .PP .Vb 1 \& *CORE::GLOBAL::open = sub(*;$@) {...} .Ve .PP Any code which is loaded \fB\s-1AFTER\s0\fR this happens will use the alternate open. This means you can place your \f(CW\*(C`use Test::MockFile\*(C'\fR 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. .PP We oveload the following statements and then return tied handles to enable the rest of the \s-1IO\s0 functions to work properly. Only \fBopen\fR / \&\fBsysopen\fR are needed to address file operations. However \fBopendir\fR file handles were never setup for tie so we have to override all of \&\fBopendir\fR's related functions. .IP "\(bu" 4 open .IP "\(bu" 4 sysopen .IP "\(bu" 4 opendir .IP "\(bu" 4 readdir .IP "\(bu" 4 telldir .IP "\(bu" 4 seekdir .IP "\(bu" 4 rewinddir .IP "\(bu" 4 closedir .SH "CAEATS AND LIMITATIONS" .IX Header "CAEATS AND LIMITATIONS" .SS "\s-1DEBUGGER UNDER STRICT MODE\s0" .IX Subsection "DEBUGGER UNDER STRICT MODE" If you want to use the Perl debugger (perldebug) on any code that uses Test::MockFile in strict mode, you will need to load Term::ReadLine beforehand, because it loads a file. Under the debugger, the debugger will load the module after Test::MockFile and get mad. .PP .Vb 2 \& # Load it from the command line \& perl \-MTerm::ReadLine \-d code.pl \& \& # Or alternatively, add this to the top of your code: \& use Term::ReadLine .Ve .SS "\s-1FILENO IS UNSUPPORTED\s0" .IX Subsection "FILENO IS UNSUPPORTED" Filehandles can provide the file descriptor (in number) using the \&\f(CW\*(C`fileno\*(C'\fR keyword but this is purposefully unsupported in Test::MockFile. .PP The reaosn is that by mocking a file, we're creating an alternative file system. Returning a \f(CW\*(C`fileno\*(C'\fR (file descriptor number) would require creating file descriptor numbers that would possibly conflict with the file desciptors you receive from the real filesystem. .PP In short, this is a recipe for buggy tests or worse \- truly destructive behavior. If you have a need for a real file, we suggest File::Temp. .SS "\s-1BAREWORD FILEHANDLE FAILURES\s0" .IX Subsection "BAREWORD FILEHANDLE FAILURES" There is a particular type of bareword filehandle failures that cannot be fixed. .PP 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. .PP The only solution to these is loading `Test::MockFile` after the other code: .PP This will fail: .PP .Vb 5 \& # 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\*(Aqs \& # opendir prototypes \& use Test::MockFile (); \& use Test2::V0; .Ve .PP This will succeed: .PP .Vb 4 \& # This will succeed because open() will be parsed by perl \& # and only then we override those functions \& use Test2::V0; \& use Test::MockFile (); .Ve .PP (Using strict-mode will not fix it, even though you should use it.) .SH "AUTHOR" .IX Header "AUTHOR" Todd Rinaldo, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to . .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Test::MockFile .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to Nicolas R., \f(CW\*(C`\*(C'\fR for help with Overload::FileCheck. This module could not have been completed without it. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2018 cPanel L.L.C. .PP All rights reserved. .PP .PP This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.