1Test::Directory(3) User Contributed Perl Documentation Test::Directory(3)
2
6 Test::Directory - Perl extension for maintaining test directories.
7
9 use Test::Directory
10 use My::Module
11 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
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 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 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 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 The directory will be automatically cleaned up when the object goes out
44 of scope; see the clean method below for details.
45 CONSTRUCTOR
47 new([$path, $options, ...])
48 Create a new instance pointing to the specified $path. $options is
49 an optional hashref of options.
50 $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 UTILITY METHODS
56 touch($file ...)
57 Create the specified $files and track their state.
58 create($file,%options)
60 Create the specified $file and track its state. The %options hash
61 supports the following:
62 time => $timestamp
64 Passed to "utime" in perlfunc to set the files access and
65 modification times.
66 content => $data
68 Write $data to the file.
69 mkdir($directory)
71 Create the specified $directory; dies if mkdir fails.
72 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 For portability, this method implicitly splits the path on UNIX-
79 style / seperators, and rejoins it with the local directory
80 seperator.
81 Absent any seperator substitution, the returned value would be
83 equivalent to $file.
84 path($file)
86 Returns the path for the $file, including the directory name and
87 any substitutions. $file need not exist.
88 check_file($file)
90 Checks whether the specified $file exists, and updates its state
91 accordingly. Returns true if $file exists, false otherwise.
92 This method is used internally by the corresponding test methods.
94 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 This method is used internally by the corresponding test methods.
101 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 remove_files($file...)
107 Remove the specified $files; return the number of files removed.
108 remove_directories($directory...)
110 Remove the specified $directoriess; return the number of
111 directories removed.
112 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 This method is called automatically when the object goes out of
120 scope.
121 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 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 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 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 is_ok($test_name)
145 Pass if the test directory has no missing or extra files.
146 clean_ok([$test_name])
148 Equivalent to ok(clean,$test_name)
149 EXAMPLES
151 Calling an external program to move a file
152 $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
160 Test::Builder
161
163 Steve Sanbeg, <sanbeg@cpan.org<gt>
164
166 Copyright (C) 2013 by Steve Sanbeg
167 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.
171perl v5.38.0 2023-07-21 Test::Directory(3)