Test::File(3pm)

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

NAME

6       Test::File -- test file attributes
7

SYNOPSIS

9         use Test::File;
10

DESCRIPTION

12       This modules provides a collection of test utilities for file
13       attributes.
14
15       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
20       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
27       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
31   Functions
32       has_symlinks
33           Returns true is this module thinks that the current system supports
34           symlinks.
35
36           This is not a test function. It's something that tests can use to
37           determine what it should expect or skip.
38
39       file_exists_ok( FILENAME [, NAME ] )
40           Ok if the file exists, and not ok otherwise.
41
42       file_not_exists_ok( FILENAME [, NAME ] )
43           Ok if the file does not exist, and not okay if it does exist.
44
45       file_empty_ok( FILENAME [, NAME ] )
46           Ok if the file exists and has empty size, not ok if the file does
47           not exist or exists with non-zero size.
48
49           Previously this tried to test any sort of file. Sometime in the
50           future this will fail if the argument is not a plain file or is a
51           directory.
52
53       file_not_empty_ok( FILENAME [, NAME ] )
54           Ok if the file exists and has non-zero size, not ok if the file
55           does not exist or exists with zero size.
56
57           Previously this tried to test any sort of file. Sometime in the
58           future this will fail if the argument is not a plain file or is a
59           directory.
60
61       file_size_ok( FILENAME, SIZE [, NAME ]  )
62           Ok if the file exists and has SIZE size in bytes (exactly), not ok
63           if the file does not exist or exists with size other than SIZE.
64
65           Previously this tried to test any sort of file. Sometime in the
66           future this will fail if the argument is not a plain file or is a
67           directory.
68
69       file_max_size_ok( FILENAME, MAX [, NAME ] )
70           Ok if the file exists and has size less than or equal to MAX bytes,
71           not ok if the file does not exist or exists with size greater than
72           MAX bytes.
73
74           Previously this tried to test any sort of file. Sometime in the
75           future this will fail if the argument is not a plain file or is a
76           directory.
77
78       file_min_size_ok( FILENAME, MIN [, NAME ] )
79           Ok if the file exists and has size greater than or equal to MIN
80           bytes, not ok if the file does not exist or exists with size less
81           than MIN bytes.
82
83           Previously this tried to test any sort of file. Sometime in the
84           future this will fail if the argument is not a plain file or is a
85           directory.
86
87       file_line_count_is( FILENAME, COUNT [, NAME ]  )
88           Ok if the file exists and has COUNT lines (exactly), not ok if the
89           file does not exist or exists with a line count other than COUNT.
90
91           This function uses the current value of $/ as the line ending and
92           counts the lines by reading them and counting how many it read.
93
94           Previously this tried to test any sort of file. Sometime in the
95           future this will fail if the argument is not a plain file or is a
96           directory.
97
98       file_line_count_isnt( FILENAME, COUNT [, NAME ]  )
99           Ok if the file exists and doesn't have exactly COUNT lines, not ok
100           if the file does not exist or exists with a line count of COUNT.
101           Read that carefully: the file must exist for this test to pass!
102
103           This function uses the current value of $/ as the line ending and
104           counts the lines by reading them and counting how many it read.
105
106           Previously this tried to test any sort of file. Sometime in the
107           future this will fail if the argument is not a plain file or is a
108           directory.
109
110       file_line_count_between( FILENAME, MIN, MAX, [, NAME ]  )
111           Ok if the file exists and has a line count between MIN and MAX,
112           inclusively.
113
114           This function uses the current value of $/ as the line ending and
115           counts the lines by reading them and counting how many it read.
116
117           Previously this tried to test any sort of file. Sometime in the
118           future this will fail if the argument is not a plain file or is a
119           directory.
120
121       file_contains_like ( FILENAME, PATTERN [, NAME ] )
122           Ok if the file exists and its contents (as one big string) match
123           PATTERN, not ok if the file does not exist, is not readable, or
124           exists but doesn't match PATTERN.
125
126           Since the file contents are read into memory, you should not use
127           this for large files.  Besides memory consumption, test diagnostics
128           for failing tests might be difficult to decipher.  However, for
129           short files this works very well.
130
131           Because the entire contents are treated as one large string, you
132           can make a pattern that tests multiple lines.  Don't forget that
133           you may need to use the /s modifier for such patterns:
134
135                   # make sure file has one or more paragraphs with CSS class X
136                   file_contains_like($html_file, qr{<p class="X">.*?</p>}s);
137
138           Contrariwise, if you need to match at the beginning or end of a
139           line inside the file, use the /m modifier:
140
141                   # make sure file has a setting for foo
142                   file_contains_like($config_file, qr/^ foo \s* = \s* \w+ $/mx);
143
144           If you want to test your file contents against multiple patterns,
145           but don't want to have the file read in repeatedly, you can pass an
146           arrayref of patterns instead of a single pattern, like so:
147
148                   # make sure our template has rendered correctly
149                   file_contains_like($template_out,
150                           [
151                           qr/^ $title_line $/mx,
152                           map { qr/^ $_ $/mx } @chapter_headings,
153                           qr/^ $footer_line $/mx,
154                           ]);
155
156           Please note that if you do this, and your file does not exist or is
157           not readable, you'll only get one test failure instead of a failure
158           for each pattern.  This could cause your test plan to be off,
159           although you may not care at that point because your test failed
160           anyway.  If you do care, either skip the test plan altogether by
161           employing Test::More's done_testing() function, or use
162           "file_readable_ok" in conjunction with a "SKIP" block.
163
164           Contributed by Buddy Burden "<barefoot@cpan.org>".
165
166       file_contains_unlike ( FILENAME, PATTERN [, NAME ] )
167           Ok if the file exists and its contents (as one big string) do not
168           match PATTERN, not ok if the file does not exist, is not readable,
169           or exists but matches PATTERN.
170
171           All notes and caveats for "file_contains_like" apply to this
172           function as well.
173
174           Contributed by Buddy Burden "<barefoot@cpan.org>".
175
176       file_contains_utf8_like ( FILENAME, PATTERN [, NAME ] )
177           The same as "file_contains_like", except the file is opened as
178           UTF-8.
179
180       file_contains_utf8_unlike ( FILENAME, PATTERN [, NAME ] )
181           The same as "file_contains_unlike", except the file is opened as
182           UTF-8.
183
184       file_contains_encoded_like ( FILENAME, ENCODING, PATTERN [, NAME ] )
185           The same as "file_contains_like", except the file is opened with
186           ENCODING
187
188       file_contains_encoded_unlike ( FILENAME, ENCODING, PATTERN [, NAME ] )
189           The same as "file_contains_unlike", except the file is opened with
190           ENCODING.
191
192       file_readable_ok( FILENAME [, NAME ] )
193           Ok if the file exists and is readable, not ok if the file does not
194           exist or is not readable.
195
196       file_not_readable_ok( FILENAME [, NAME ] )
197           Ok if the file exists and is not readable, not ok if the file does
198           not exist or is readable.
199
200       file_writable_ok( FILENAME [, NAME ] )
201       file_writeable_ok( FILENAME [, NAME ] )
202           Ok if the file exists and is writable, not ok if the file does not
203           exist or is not writable.
204
205           The original name is "file_writeable_ok" with that extra e. That
206           still works but there's a function with the correct spelling too.
207
208       file_not_writeable_ok( FILENAME [, NAME ] )
209       file_not_writable_ok( FILENAME [, NAME ] )
210           Ok if the file exists and is not writable, not ok if the file does
211           not exist or is writable.
212
213           The original name is "file_not_writeable_ok" with that extra e.
214           That still works but there's a function with the correct spelling
215           too.
216
217       file_executable_ok( FILENAME [, NAME ] )
218           Ok if the file exists and is executable, not ok if the file does
219           not exist or is not executable.
220
221           This test automatically skips if it thinks it is on a Windows
222           platform.
223
224       file_not_executable_ok( FILENAME [, NAME ] )
225           Ok if the file exists and is not executable, not ok if the file
226           does not exist or is executable.
227
228           This test automatically skips if it thinks it is on a Windows
229           platform.
230
231       file_mode_is( FILENAME, MODE [, NAME ] )
232           Ok if the file exists and the mode matches, not ok if the file does
233           not exist or the mode does not match.
234
235           This test automatically skips if it thinks it is on a Windows
236           platform.
237
238           Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
239
240       file_mode_isnt( FILENAME, MODE [, NAME ] )
241           Ok if the file exists and mode does not match, not ok if the file
242           does not exist or mode does match.
243
244           This test automatically skips if it thinks it is on a Windows
245           platform.
246
247           Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
248
249       file_mode_has( FILENAME, MODE [, NAME ] )
250           Ok if the file exists and has all the bits in mode turned on, not
251           ok if the file does not exist or the mode does not match.  That is,
252           "FILEMODE & MODE == MODE" must be true.
253
254           This test automatically skips if it thinks it is on a Windows
255           platform.
256
257           Contributed by Ricardo Signes "<rjbs@cpan.org>"
258
259       file_mode_hasnt( FILENAME, MODE [, NAME ] )
260           Ok if the file exists and has all the bits in mode turned off, not
261           ok if the file does not exist or the mode does not match.  That is,
262           "FILEMODE & MODE == 0" must be true.
263
264           This test automatically skips if it thinks it is on a Windows
265           platform.
266
267           Contributed by Ricardo Signes "<rjbs@cpan.org>"
268
269       file_is_symlink_ok( FILENAME [, NAME ] )
270           Ok if FILENAME is a symlink, even if it points to a non-existent
271           file. This test automatically skips if the operating system does
272           not support symlinks.
273
274       file_is_not_symlink_ok( FILENAME [, NAME ] )
275           Ok if FILENAME is a not symlink. This test automatically skips if
276           the operating system does not support symlinks. If the file does
277           not exist, the test fails.
278
279       symlink_target_exists_ok( SYMLINK [, TARGET] [, NAME ] )
280           Ok if FILENAME is a symlink and it points to a existing file. With
281           the optional TARGET argument, the test fails if SYMLINK's target is
282           not TARGET. This test automatically skips if the operating system
283           does not support symlinks. If the file does not exist, the test
284           fails.
285
286       symlink_target_dangles_ok( SYMLINK [, NAME ] )
287           Ok if FILENAME is a symlink and if it doesn't point to a existing
288           file. This test automatically skips if the operating system does
289           not support symlinks. If the file does not exist, the test fails.
290
291       symlink_target_is( SYMLINK, TARGET [, NAME ] )
292           Ok if FILENAME is a symlink and if points to TARGET. This test
293           automatically skips if the operating system does not support
294           symlinks.  If the file does not exist, the test fails.
295
296       symlink_target_is_absolute_ok( SYMLINK [, NAME ] )
297           Ok if FILENAME is a symlink and if its target is an absolute path.
298           This test automatically skips if the operating system does not
299           support symlinks. If the file does not exist, the test fails.
300
301       dir_exists_ok( DIRECTORYNAME [, NAME ] )
302           Ok if the file exists and is a directory, not ok if the file
303           doesn't exist, or exists but isn't a directory.
304
305           Contributed by Buddy Burden "<barefoot@cpan.org>".
306
307       dir_contains_ok( DIRECTORYNAME, FILENAME [, NAME ] )
308           Ok if the directory exists and contains the file, not ok if the
309           directory doesn't exist, or exists but doesn't contain the file.
310
311           Contributed by Buddy Burden "<barefoot@cpan.org>".
312
313       link_count_is_ok( FILE, LINK_COUNT [, NAME ] )
314           Ok if the link count to FILE is LINK_COUNT. LINK_COUNT is
315           interpreted as an integer. A LINK_COUNT that evaluates to 0 returns
316           Ok if the file does not exist.
317
318       link_count_gt_ok( FILE, LINK_COUNT [, NAME ] )
319           Ok if the link count to FILE is greater than LINK_COUNT. LINK_COUNT
320           is interpreted as an integer. A LINK_COUNT that evaluates to 0
321           returns Ok if the file has at least one link.
322
323       link_count_lt_ok( FILE, LINK_COUNT [, NAME ] )
324           Ok if the link count to FILE is less than LINK_COUNT. LINK_COUNT is
325           interpreted as an integer. A LINK_COUNT that evaluates to 0 returns
326           Ok if the file has at least one link.
327
328       owner_is( FILE , OWNER [, NAME ] )
329           Ok if FILE's owner is the same as OWNER.  OWNER may be a text user
330           name or a numeric userid.  Test skips on Dos, and Mac OS <= 9.  If
331           the file does not exist, the test fails.
332
333           Contributed by Dylan Martin
334
335       owner_isnt( FILE, OWNER [, NAME ] )
336           Ok if FILE's owner is not the same as OWNER.  OWNER may be a text
337           user name or a numeric userid.  Test skips on Dos and Mac OS <= 9.
338           If the file does not exist, the test fails.
339
340           Contributed by Dylan Martin
341
342       group_is( FILE , GROUP [, NAME ] )
343           Ok if FILE's group is the same as GROUP.  GROUP may be a text group
344           name or a numeric group id.  Test skips on Dos, Mac OS <= 9 and any
345           other operating systems that do not support getpwuid() and friends.
346           If the file does not exist, the test fails.
347
348           Contributed by Dylan Martin
349
350       group_isnt( FILE , GROUP [, NAME ] )
351           Ok if FILE's group is not the same as GROUP.  GROUP may be a text
352           group name or a numeric group id.  Test skips on Dos, Mac OS <= 9
353           and any other operating systems that do not support getpwuid() and
354           friends.  If the file does not exist, the test fails.
355
356           Contributed by Dylan Martin
357
358       file_mtime_age_ok( FILE [, WITHIN_SECONDS ] [, NAME ] )
359           Ok if FILE's modified time is WITHIN_SECONDS inclusive of the
360           system's current time.  This test uses stat() to obtain the mtime.
361           If the file does not exist the test returns failure. If stat()
362           fails, the test is skipped.
363
364       file_mtime_gt_ok( FILE, UNIXTIME [, NAME ] )
365           Ok if FILE's mtime is > UNIXTIME. This test uses stat() to get the
366           mtime. If stat() fails this test is skipped. If FILE does not
367           exist, this test fails.
368
369       file_mtime_lt_ok( FILE, UNIXTIME, [, NAME ] )
370           Ok if FILE's modified time is < UNIXTIME.  This test uses stat() to
371           get the mtime. If stat() fails this test is skipped. If FILE does
372           not exist, this test fails.
373

TO DO

375       * check properties for other users (readable_by_root, for instance)
376
377       * check times
378
379       * check number of links to file
380
381       * check path parts (directory, filename, extension)
382

SOURCE AVAILABILITY

390       This module is in Github:
391
392               https://github.com/briandfoy/test-file
393

AUTHOR

395       brian d foy, "<bdfoy@cpan.org>"
396

CREDITS

398       Shawn Sorichetti "<ssoriche@coloredblocks.net>" provided some
399       functions.
400
401       Tom Metro helped me figure out some Windows capabilities.
402
403       Dylan Martin added "owner_is" and "owner_isnt".
404
405       David Wheeler added "file_line_count_is".
406
407       Buddy Burden "<barefoot@cpan.org>" provided "dir_exists_ok",
408       "dir_contains_ok", "file_contains_like", and "file_contains_unlike".
409
410       xmikew "<https://github.com/xmikew>" provided the "mtime_age" stuff.
411
412       Torbjørn Lindahl is working on Test2::Tools::File and we're working
413       together to align our interfaces.
414
415       Jean-Damien Durand added bits to use Win32::IsSymlinkCreationAllowed,
416       new since Win32 0.55.
417

COPYRIGHT AND LICENSE

419       Copyright © 2002-2023, brian d foy <bdfoy@cpan.org>. All rights
420       reserved.
421
422       This program is free software; you can redistribute it and/or modify it
423       under the terms of the Artistic License 2.0
424
425
426
427perl v5.38.0                      2023-08-08                     Test::File(3)