1Test::Directory(3)    User Contributed Perl Documentation   Test::Directory(3)
2
3
4

NAME

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

SYNOPSIS

9        use Test::Directory
10        use My::Module
11
12        my $dir = Test::Directory->new($path);
13        $dir->touch($src_file);
14        My::Module::something( $dir->path($src_file), $dir->path($dst_file) );
15        $dir->has_ok($dst_file);   #did my module create dst?
16        $dir->hasnt_ok($src_file); #is source still there?
17

DESCRIPTION

19       Testing code can involve making sure that files are created and deleted
20       as expected.  Doing this manually can be error prone, as it's easy to
21       forget a file, or miss that some unexpected file was added. This module
22       simplifies maintaining test directories by tracking their status as
23       they are modified or tested with this API, making it simple to test
24       both individual files, as well as to verify that there are no missing
25       or unknown files.
26
27       The idea is to use this API to create a temporary directory and
28       populate an initial set of files.  Then, whenever something in the
29       directory is changes, use the test methods to verify that the change
30       happened as expected.  At any time, it is simple to verify that the
31       contents of the directory are exactly as expected.
32
33       Test::Directory implements an object-oriented interface for managing
34       test directories.  It tracks which files it knows about (by creating or
35       testing them via its API), and can report if any files were missing or
36       unexpectedly added.
37
38       There are two flavors of methods for interacting with the directory.
39       Utility methods simply return a value (i.e. the number of files/errors)
40       with no output, while the Test functions use Test::Builder to produce
41       the approriate test results and diagnostics for the test harness.
42
43       The directory will be automatically cleaned up when the object goes out
44       of scope; see the clean method below for details.
45
46   CONSTRUCTOR
47       new([$path, $options, ...])
48           Create a new instance pointing to the specified $path. $options is
49           an optional hashref of options.
50
51           $path will be created (or the constructor will die).  If $path is
52           undefined, a unique path will be automatically generated; otherwise
53           it is an error for $path to already exist.
54
55   UTILITY METHODS
56       touch($file ...)
57           Create the specified $files and track their state.
58
59       create($file,%options)
60           Create the specified $file and track its state.  The %options hash
61           supports the following:
62
63           time => $timestamp
64                   Passed to "utime" in perlfunc to set the files access and
65                   modification times.
66
67           content => $data
68                   Write $data to the file.
69
70       mkdir($directory)
71           Create the specified $directory; dies if mkdir fails.
72
73       name($file)
74           Returns the name of the $file, relative to the directory; including
75           any seperator normalization.  $file need not exist.  This method is
76           used internally by most other methods to translate file paths.
77
78           For portability, this method implicitly splits the path on UNIX-
79           style / seperators, and rejoins it with the local directory
80           seperator.
81
82           Absent any seperator substitution, the returned value would be
83           equivalent to $file.
84
85       path($file)
86           Returns the path for the $file, including the directory name and
87           any substitutions.  $file need not exist.
88
89       check_file($file)
90           Checks whether the specified $file exists, and updates its state
91           accordingly.  Returns true if $file exists, false otherwise.
92
93           This method is used internally by the corresponding test methods.
94
95       check_directory($directory)
96           Checks whether the specified $directory exists, and updates its
97           state accordingly.  Returns true if $directory exists, false
98           otherwise.
99
100           This method is used internally by the corresponding test methods.
101
102           Note that replacing a file with a directory, or vice versa, would
103           require calling both check_file and check_directory to update the
104           state to reflect both changes.
105
106       remove_files($file...)
107           Remove the specified $files; return the number of files removed.
108
109       remove_directories($directory...)
110           Remove the specified $directoriess; return the number of
111           directories removed.
112
113       clean
114           Remove all known files, then call rmdir on the directory; returns
115           the status of the rmdir.  The presence of any unknown files will
116           cause the rmdir to fail, leaving the directory with these unknown
117           files.
118
119           This method is called automatically when the object goes out of
120           scope.
121
122       count_unknown
123       count_missing
124           Returns a count of the unknown or missing files and directories.
125           Note that files and directores are interchangeable when counting
126           missing files, but not when counting unknown files.
127
128   TEST METHODS
129       The test methods validate the state of the test directory, calling
130       Test::Builder's ok and diag methods to generate output.
131
132       has  ($file, $test_name)
133       hasnt($file, $test_name)
134           Verify the status of $file, and update its state.  The test will
135           pass if the state is expected.  If $test_name is undefined, a
136           default will be generated.
137
138       has_dir  ($directory, $test_name);
139       hasnt_dir($directory, $test_name);
140           Verify the status of $directory, and update its state.  The test
141           will pass if the state is expected.  If $test_name is undefined, a
142           default will be generated.
143
144       is_ok($test_name)
145           Pass if the test directory has no missing or extra files.
146
147       clean_ok([$test_name])
148           Equivalent to ok(clean,$test_name)
149
150   EXAMPLES
151       Calling an external program to move a file
152
153        $dir->touch('my-file.txt');
154        system ('gzip', $dir->path('my-file.txt'));
155        $dir->has  ('my-file.txt.gz', '.gz file is added');
156        $dir->hasnt('my-file.txt',    '.txt file is removed');
157        $dir->is_ok; #verify no other changes to $dir
158

SEE ALSO

160       Test::Builder
161

AUTHOR

163       Steve Sanbeg, <sanbeg@cpan.org<gt>
164
166       Copyright (C) 2013 by Steve Sanbeg
167
168       This library is free software; you can redistribute it and/or modify it
169       under the same terms as Perl itself, either Perl version 5.10.1 or, at
170       your option, any later version of Perl 5 you may have available.
171
172
173
174perl v5.38.0                      2023-07-21                Test::Directory(3)
Impressum