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

TO DO

368       * check properties for other users (readable_by_root, for instance)
369
370       * check times
371
372       * check number of links to file
373
374       * check path parts (directory, filename, extension)
375

SOURCE AVAILABILITY

383       This module is in Github:
384
385               https://github.com/briandfoy/test-file.git
386

AUTHOR

388       brian d foy, "<bdfoy@cpan.org>"
389

CREDITS

391       Shawn Sorichetti "<ssoriche@coloredblocks.net>" provided some
392       functions.
393
394       Tom Metro helped me figure out some Windows capabilities.
395
396       Dylan Martin added "owner_is" and "owner_isnt".
397
398       David Wheeler added "file_line_count_is".
399
400       Buddy Burden "<barefoot@cpan.org>" provided "dir_exists_ok",
401       "dir_contains_ok", "file_contains_like", and "file_contains_unlike".
402
403       xmikew "<https://github.com/xmikew>" provided the "mtime_age" stuff.
404
405       Torbjørn Lindahl is working on Test2::Tools::File and we're working
406       together to align our interfaces.
407

COPYRIGHT AND LICENSE

409       Copyright © 2002-2022, brian d foy <bdfoy@cpan.org>. All rights
410       reserved.
411
412       This program is free software; you can redistribute it and/or modify it
413       under the terms of the Artistic License 2.0
414
415
416
417perl v5.34.0                      2022-02-16                     Test::File(3)