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->has_ok($src_file); #is source still there?
$dir->has_ok($dst_file); #did my module create dst?DESCRIPTION
Sometimes, testing code involves making sure that files are created and deleted as expected. 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.
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 it necessary. If $options->{unique} is set, 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 to set the files access and modification times.
- content $data
-
Write $data to the file.
- name(FILE)
-
Returns the name of the FILE, relative to the directory; including any template substitutions. FILE need not exist.
- path(FILE)
-
Returns the path for the FILE, including the directory name and any template 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.
- remove_files($file...)
-
Remove the specified $files; return the number of files 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.
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.
- is_ok($test_name)
-
Pass if the test directory has no missing or extra files.
- clean_ok([TEXT])
-
Equivalent to ok(clean,TEXT)
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 $dirSEE ALSO
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.