1Test::File(3) User Contributed Perl Documentation Test::File(3)
2
6 Test::File -- test file attributes
7
9 use Test::File;
10
12 This modules provides a collection of test utilities for file
13 attributes.
14 Some file attributes depend on the owner of the process testing the
16 file in the same way the file test operators do. For instance, root
17 (or super-user or Administrator) may always be able to read files no
18 matter the permissions.
19 Some attributes don't make sense outside of Unix, either, so some tests
21 automatically skip if they think they won't work on the platform. If
22 you have a way to make these functions work on Windows, for instance,
23 please send me a patch. :) IF you want to pretend to be Windows on a
24 non-Windows machine (for instance, to test "skip()"), you can set the
25 "PRETEND_TO_BE_WINDOWS" environment variable.
26 The optional NAME parameter for every function allows you to specify a
28 name for the test. If not supplied, a reasonable default will be
29 generated.
30 Functions
32 file_exists_ok( FILENAME [, NAME ] )
33 Ok if the file exists, and not ok otherwise.
34 file_not_exists_ok( FILENAME [, NAME ] )
36 Ok if the file does not exist, and not okay if it does exist.
37 file_empty_ok( FILENAME [, NAME ] )
39 Ok if the file exists and has empty size, not ok if the file does
40 not exist or exists with non-zero size.
41 file_not_empty_ok( FILENAME [, NAME ] )
43 Ok if the file exists and has non-zero size, not ok if the file
44 does not exist or exists with zero size.
45 file_size_ok( FILENAME, SIZE [, NAME ] )
47 Ok if the file exists and has SIZE size in bytes (exactly), not ok
48 if the file does not exist or exists with size other than SIZE.
49 file_max_size_ok( FILENAME, MAX [, NAME ] )
51 Ok if the file exists and has size less than or equal to MAX bytes,
52 not ok if the file does not exist or exists with size greater than
53 MAX bytes.
54 file_min_size_ok( FILENAME, MIN [, NAME ] )
56 Ok if the file exists and has size greater than or equal to MIN
57 bytes, not ok if the file does not exist or exists with size less
58 than MIN bytes.
59 file_line_count_is( FILENAME, COUNT [, NAME ] )
61 Ok if the file exists and has COUNT lines (exactly), not ok if the
62 file does not exist or exists with a line count other than COUNT.
63 This function uses the current value of $/ as the line ending and
65 counts the lines by reading them and counting how many it read.
66 file_line_count_isnt( FILENAME, COUNT [, NAME ] )
68 Ok if the file exists and doesn't have exactly COUNT lines, not ok
69 if the file does not exist or exists with a line count of COUNT.
70 Read that carefully: the file must exist for this test to pass!
71 This function uses the current value of $/ as the line ending and
73 counts the lines by reading them and counting how many it read.
74 file_line_count_between( FILENAME, MIN, MAX, [, NAME ] )
76 Ok if the file exists and has a line count between MIN and MAX,
77 inclusively.
78 This function uses the current value of $/ as the line ending and
80 counts the lines by reading them and counting how many it read.
81 file_contains_like ( FILENAME, PATTERN [, NAME ] )
83 Ok if the file exists and its contents (as one big string) match
84 PATTERN, not ok if the file does not exist, is not readable, or
85 exists but doesn't match PATTERN.
86 Since the file contents are read into memory, you should not use
88 this for large files. Besides memory consumption, test diagnostics
89 for failing tests might be difficult to decipher. However, for
90 short files this works very well.
91 Because the entire contents are treated as one large string, you
93 can make a pattern that tests multiple lines. Don't forget that
94 you may need to use the /s modifier for such patterns:
95 # make sure file has one or more paragraphs with CSS class X
97 file_contains_like($html_file, qr{<p class="X">.*?</p>}s);
98 Contrariwise, if you need to match at the beginning or end of a
100 line inside the file, use the /m modifier:
101 # make sure file has a setting for foo
103 file_contains_like($config_file, qr/^ foo \s* = \s* \w+ $/mx);
104 If you want to test your file contents against multiple patterns,
106 but don't want to have the file read in repeatedly, you can pass an
107 arrayref of patterns instead of a single pattern, like so:
108 # make sure our template has rendered correctly
110 file_contains_like($template_out,
111 [
112 qr/^ $title_line $/mx,
113 map { qr/^ $_ $/mx } @chapter_headings,
114 qr/^ $footer_line $/mx,
115 ]);
116 Please note that if you do this, and your file does not exist or is
118 not readable, you'll only get one test failure instead of a failure
119 for each pattern. This could cause your test plan to be off,
120 although you may not care at that point because your test failed
121 anyway. If you do care, either skip the test plan altogether by
122 employing Test::More's "done_testing()" function, or use
123 "file_readable_ok" in conjunction with a "SKIP" block.
124 Contributed by Buddy Burden "<barefoot@cpan.org>".
126 file_contains_unlike ( FILENAME, PATTERN [, NAME ] )
128 Ok if the file exists and its contents (as one big string) do not
129 match PATTERN, not ok if the file does not exist, is not readable,
130 or exists but matches PATTERN.
131 All notes and caveats for "file_contains_like" apply to this
133 function as well.
134 Contributed by Buddy Burden "<barefoot@cpan.org>".
136 file_contains_utf8_like ( FILENAME, PATTERN [, NAME ] )
138 The same as "file_contains_like", except the file is opened as
139 UTF-8.
140 file_contains_utf8_unlike ( FILENAME, PATTERN [, NAME ] )
142 The same as "file_contains_unlike", except the file is opened as
143 UTF-8.
144 file_contains_encoded_like ( FILENAME, ENCODING, PATTERN [, NAME ] )
146 The same as "file_contains_like", except the file is opened with
147 ENCODING
148 file_contains_encoded_unlike ( FILENAME, ENCODING, PATTERN [, NAME ] )
150 The same as "file_contains_unlike", except the file is opened with
151 ENCODING.
152 file_readable_ok( FILENAME [, NAME ] )
154 Ok if the file exists and is readable, not ok if the file does not
155 exist or is not readable.
156 file_not_readable_ok( FILENAME [, NAME ] )
158 Ok if the file exists and is not readable, not ok if the file does
159 not exist or is readable.
160 file_writeable_ok( FILENAME [, NAME ] )
162 Ok if the file exists and is writeable, not ok if the file does not
163 exist or is not writeable.
164 file_not_writeable_ok( FILENAME [, NAME ] )
166 Ok if the file exists and is not writeable, not ok if the file does
167 not exist or is writeable.
168 file_executable_ok( FILENAME [, NAME ] )
170 Ok if the file exists and is executable, not ok if the file does
171 not exist or is not executable.
172 This test automatically skips if it thinks it is on a Windows
174 platform.
175 file_not_executable_ok( FILENAME [, NAME ] )
177 Ok if the file exists and is not executable, not ok if the file
178 does not exist or is executable.
179 This test automatically skips if it thinks it is on a Windows
181 platform.
182 file_mode_is( FILENAME, MODE [, NAME ] )
184 Ok if the file exists and the mode matches, not ok if the file does
185 not exist or the mode does not match.
186 This test automatically skips if it thinks it is on a Windows
188 platform.
189 Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
191 file_mode_isnt( FILENAME, MODE [, NAME ] )
193 Ok if the file exists and mode does not match, not ok if the file
194 does not exist or mode does match.
195 This test automatically skips if it thinks it is on a Windows
197 platform.
198 Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
200 file_mode_has( FILENAME, MODE [, NAME ] )
202 Ok if the file exists and has all the bits in mode turned on, not
203 ok if the file does not exist or the mode does not match. That is,
204 "FILEMODE & MODE == MODE" must be true.
205 This test automatically skips if it thinks it is on a Windows
207 platform.
208 Contributed by Ricardo Signes "<rjbs@cpan.org>"
210 file_mode_hasnt( FILENAME, MODE [, NAME ] )
212 Ok if the file exists and has all the bits in mode turned off, not
213 ok if the file does not exist or the mode does not match. That is,
214 "FILEMODE & MODE == 0" must be true.
215 This test automatically skips if it thinks it is on a Windows
217 platform.
218 Contributed by Ricardo Signes "<rjbs@cpan.org>"
220 file_is_symlink_ok( FILENAME [, NAME ] )
222 Ok if FILENAME is a symlink, even if it points to a non-existent
223 file. This test automatically skips if the operating system does
224 not support symlinks. If the file does not exist, the test fails.
225 symlink_target_exists_ok( SYMLINK [, TARGET] [, NAME ] )
227 Ok if FILENAME is a symlink and it points to a existing file. With
228 the optional TARGET argument, the test fails if SYMLINK's target is
229 not TARGET. This test automatically skips if the operating system
230 does not support symlinks. If the file does not exist, the test
231 fails.
232 symlink_target_dangles_ok( SYMLINK [, NAME ] )
234 Ok if FILENAME is a symlink and if it doesn't point to a existing
235 file. This test automatically skips if the operating system does
236 not support symlinks. If the file does not exist, the test fails.
237 symlink_target_is( SYMLINK, TARGET [, NAME ] )
239 Ok if FILENAME is a symlink and if points to TARGET. This test
240 automatically skips if the operating system does not support
241 symlinks. If the file does not exist, the test fails.
242 symlink_target_is_absolute_ok( SYMLINK [, NAME ] )
244 Ok if FILENAME is a symlink and if its target is an absolute path.
245 This test automatically skips if the operating system does not
246 support symlinks. If the file does not exist, the test fails.
247 dir_exists_ok( DIRECTORYNAME [, NAME ] )
249 Ok if the file exists and is a directory, not ok if the file
250 doesn't exist, or exists but isn't a directory.
251 Contributed by Buddy Burden "<barefoot@cpan.org>".
253 dir_contains_ok( DIRECTORYNAME, FILENAME [, NAME ] )
255 Ok if the directory exists and contains the file, not ok if the
256 directory doesn't exist, or exists but doesn't contain the file.
257 Contributed by Buddy Burden "<barefoot@cpan.org>".
259 link_count_is_ok( FILE, LINK_COUNT [, NAME ] )
261 Ok if the link count to FILE is LINK_COUNT. LINK_COUNT is
262 interpreted as an integer. A LINK_COUNT that evaluates to 0 returns
263 Ok if the file does not exist.
264 link_count_gt_ok( FILE, LINK_COUNT [, NAME ] )
266 Ok if the link count to FILE is greater than LINK_COUNT. LINK_COUNT
267 is interpreted as an integer. A LINK_COUNT that evaluates to 0
268 returns Ok if the file has at least one link.
269 link_count_lt_ok( FILE, LINK_COUNT [, NAME ] )
271 Ok if the link count to FILE is less than LINK_COUNT. LINK_COUNT is
272 interpreted as an integer. A LINK_COUNT that evaluates to 0 returns
273 Ok if the file has at least one link.
274 owner_is( FILE , OWNER [, NAME ] )
276 Ok if FILE's owner is the same as OWNER. OWNER may be a text user
277 name or a numeric userid. Test skips on Dos, and Mac OS <= 9. If
278 the file does not exist, the test fails.
279 Contributed by Dylan Martin
281 owner_isnt( FILE, OWNER [, NAME ] )
283 Ok if FILE's owner is not the same as OWNER. OWNER may be a text
284 user name or a numeric userid. Test skips on Dos and Mac OS <= 9.
285 If the file does not exist, the test fails.
286 Contributed by Dylan Martin
288 group_is( FILE , GROUP [, NAME ] )
290 Ok if FILE's group is the same as GROUP. GROUP may be a text group
291 name or a numeric group id. Test skips on Dos, Mac OS <= 9 and any
292 other operating systems that do not support getpwuid() and friends.
293 If the file does not exist, the test fails.
294 Contributed by Dylan Martin
296 group_isnt( FILE , GROUP [, NAME ] )
298 Ok if FILE's group is not the same as GROUP. GROUP may be a text
299 group name or a numeric group id. Test skips on Dos, Mac OS <= 9
300 and any other operating systems that do not support getpwuid() and
301 friends. If the file does not exist, the test fails.
302 Contributed by Dylan Martin
304 file_mtime_age_ok( FILE [, WITHIN_SECONDS ] [, NAME ] )
306 Ok if FILE's modified time is WITHIN_SECONDS inclusive of the
307 system's current time. This test uses stat() to obtain the mtime.
308 If the file does not exist the test returns failure. If stat()
309 fails, the test is skipped.
310 file_mtime_gt_ok( FILE, UNIXTIME [, NAME ] )
312 Ok if FILE's mtime is > UNIXTIME. This test uses stat() to get the
313 mtime. If stat() fails this test is skipped. If FILE does not
314 exist, this test fails.
315 file_mtime_lt_ok( FILE, UNIXTIME, [, NAME ] )
317 Ok if FILE's modified time is < UNIXTIME. This test uses stat() to
318 get the mtime. If stat() fails this test is skipped. If FILE does
319 not exist, this test fails.
320
322 * check properties for other users (readable_by_root, for instance)
323 * check times
325 * check number of links to file
327 * check path parts (directory, filename, extension)
329
331 Test::Builder, Test::More
332
334 This module is in Github:
335 git://github.com/briandfoy/test-file.git
337
339 brian d foy, "<bdfoy@cpan.org>"
340
342 Shawn Sorichetti "<ssoriche@coloredblocks.net>" provided some
343 functions.
344 Tom Metro helped me figure out some Windows capabilities.
346 Dylan Martin added "owner_is" and "owner_isnt".
348 David Wheeler added "file_line_count_is".
350 Buddy Burden "<barefoot@cpan.org>" provided "dir_exists_ok",
352 "dir_contains_ok", "file_contains_like", and "file_contains_unlike".
353 xmikew "<https://github.com/xmikew>" provided the "mtime_age" stuff.
355
357 Copyright © 2002-2016, brian d foy <bdfoy@cpan.org>. All rights
358 reserved.
359 This program is free software; you can redistribute it and/or modify it
361 under the same terms as Perl itself.
362perl v5.30.0 2019-07-26 Test::File(3)