NAME

Test::Directory - Perl extension for maintaining test directories.

SYNOPSIS

 use Test::Directory
 use My::Module

 my $dir = Test::Directory->new($path);
 $dir->touch($src_file);
 My::Module::something( $dir->path($src_file), $dir->path($dst_file) );
 $dir->has_ok($dst_file);   #did my module create dst?
 $dir->hasnt_ok($src_file); #is source still there?

DESCRIPTION

Testing code can involve making sure that files are created and deleted as expected. Doing this manually can be error prone, as it's easy to forget a file, or miss that some unexpected file was added. This module simplifies maintaining test directories by tracking their status as they are modified or tested with this API, making it simple to test both individual files, as well as to verify that there are no missing or unknown files.

The idea is to use this API to create a temporary directory and populate an initial set of files. Then, whenever something in the directory is changes, use the test methods to verify that the change happened as expected. At any time, it is simple to verify that the contents of the directory are exactly as expected.

Test::Directory implements an object-oriented interface for managing test directories. It tracks which files it knows about (by creating or testing them via its API), and can report if any files were missing or unexpectedly added.

There are two flavors of methods for interacting with the directory. Utility methods simply return a value (i.e. the number of files/errors) with no output, while the Test functions use Test::Builder to produce the approriate test results and diagnostics for the test harness.

The directory will be automatically cleaned up when the object goes out of scope; see the clean method below for details.

CONSTRUCTOR

new([$path, $options, ...])

Create a new instance pointing to the specified $path. $options is an optional hashref of options.

$path will be created (or the constructor will die). If $path is undefined, a unique path will be automatically generated; otherwise it is an error for $path to already exist.

UTILITY METHODS

touch($file ...)

Create the specified $files and track their state.

create($file,%options)

Create the specified $file and track its state. The %options hash supports the following:

time => $timestamp

Passed to "utime" in perlfunc to set the files access and modification times.

content => $data

Write $data to the file.

mkdir($directory)

Create the specified $directory; dies if mkdir fails.

name($file)

Returns the name of the $file, relative to the directory; including any seperator normalization. $file need not exist. This method is used internally by most other methods to translate file paths.

For portability, this method implicitly splits the path on UNIX-style / seperators, and rejoins it with the local directory seperator.

Absent any seperator substitution, the returned value would be equivalent to $file.

path($file)

Returns the path for the $file, including the directory name and any substitutions. $file need not exist.

check_file($file)

Checks whether the specified $file exists, and updates its state accordingly. Returns true if $file exists, false otherwise.

This method is used internally by the corresponding test methods.

check_directory($directory)

Checks whether the specified $directory exists, and updates its state accordingly. Returns true if $directory exists, false otherwise.

This method is used internally by the corresponding test methods.

Note that replacing a file with a directory, or vice versa, would require calling both check_file and check_directory to update the state to reflect both changes.

remove_files($file...)

Remove the specified $files; return the number of files removed.

remove_directories($directory...)

Remove the specified $directoriess; return the number of directories removed.

clean

Remove all known files, then call rmdir on the directory; returns the status of the rmdir. The presence of any unknown files will cause the rmdir to fail, leaving the directory with these unknown files.

This method is called automatically when the object goes out of scope.

count_unknown

count_missing

Returns a count of the unknown or missing files and directories. Note that files and directores are interchangeable when counting missing files, but not when counting unknown files.

TEST METHODS

The test methods validate the state of the test directory, calling Test::Builder's ok and diag methods to generate output.

has ($file, $test_name)

hasnt($file, $test_name)

Verify the status of $file, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated.

has_dir ($directory, $test_name);

hasnt_dir($directory, $test_name);

Verify the status of $directory, and update its state. The test will pass if the state is expected. If $test_name is undefined, a default will be generated.

is_ok($test_name)

Pass if the test directory has no missing or extra files.

clean_ok([$test_name])

Equivalent to ok(clean,$test_name)

EXAMPLES

Calling an external program to move a file

 $dir->touch('my-file.txt');
 system ('gzip', $dir->path('my-file.txt'));
 $dir->has  ('my-file.txt.gz', '.gz file is added');
 $dir->hasnt('my-file.txt',    '.txt file is removed');
 $dir->is_ok; #verify no other changes to $dir

SEE ALSO

Test::Builder

AUTHOR

Steve Sanbeg, <sanbeg@cpan.org<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Steve Sanbeg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.