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       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
46       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
50       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
55       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
60       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
64           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
67       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
72           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
75       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
79           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
82       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
87           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
92           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
96                   # 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
99           Contrariwise, if you need to match at the beginning or end of a
100           line inside the file, use the /m modifier:
101
102                   # make sure file has a setting for foo
103                   file_contains_like($config_file, qr/^ foo \s* = \s* \w+ $/mx);
104
105           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
109                   # 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
117           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
125           Contributed by Buddy Burden "<barefoot@cpan.org>".
126
127       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
132           All notes and caveats for "file_contains_like" apply to this
133           function as well.
134
135           Contributed by Buddy Burden "<barefoot@cpan.org>".
136
137       file_contains_utf8_like ( FILENAME, PATTERN [, NAME ] )
138           The same as "file_contains_like", except the file is opened as
139           UTF-8.
140
141       file_contains_utf8_unlike ( FILENAME, PATTERN [, NAME ] )
142           The same as "file_contains_unlike", except the file is opened as
143           UTF-8.
144
145       file_contains_encoded_like ( FILENAME, ENCODING, PATTERN [, NAME ] )
146           The same as "file_contains_like", except the file is opened with
147           ENCODING
148
149       file_contains_encoded_unlike ( FILENAME, ENCODING, PATTERN [, NAME ] )
150           The same as "file_contains_unlike", except the file is opened with
151           ENCODING.
152
153       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
157       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
161       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
165       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
169       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
173           This test automatically skips if it thinks it is on a Windows
174           platform.
175
176       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
180           This test automatically skips if it thinks it is on a Windows
181           platform.
182
183       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
187           This test automatically skips if it thinks it is on a Windows
188           platform.
189
190           Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
191
192       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
196           This test automatically skips if it thinks it is on a Windows
197           platform.
198
199           Contributed by Shawn Sorichetti "<ssoriche@coloredblocks.net>"
200
201       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
206           This test automatically skips if it thinks it is on a Windows
207           platform.
208
209           Contributed by Ricardo Signes "<rjbs@cpan.org>"
210
211       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
216           This test automatically skips if it thinks it is on a Windows
217           platform.
218
219           Contributed by Ricardo Signes "<rjbs@cpan.org>"
220
221       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
226       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
233       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
238       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
243       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
248       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
252           Contributed by Buddy Burden "<barefoot@cpan.org>".
253
254       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
258           Contributed by Buddy Burden "<barefoot@cpan.org>".
259
260       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
265       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
270       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
275       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
280           Contributed by Dylan Martin
281
282       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
287           Contributed by Dylan Martin
288
289       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
295           Contributed by Dylan Martin
296
297       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
303           Contributed by Dylan Martin
304
305       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
311       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
316       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

TO DO

322       * check properties for other users (readable_by_root, for instance)
323
324       * check times
325
326       * check number of links to file
327
328       * check path parts (directory, filename, extension)
329

SEE ALSO

331       Test::Builder, Test::More
332

SOURCE AVAILABILITY

334       This module is in Github:
335
336               git://github.com/briandfoy/test-file.git
337

AUTHOR

339       brian d foy, "<bdfoy@cpan.org>"
340

CREDITS

342       Shawn Sorichetti "<ssoriche@coloredblocks.net>" provided some
343       functions.
344
345       Tom Metro helped me figure out some Windows capabilities.
346
347       Dylan Martin added "owner_is" and "owner_isnt".
348
349       David Wheeler added "file_line_count_is".
350
351       Buddy Burden "<barefoot@cpan.org>" provided "dir_exists_ok",
352       "dir_contains_ok", "file_contains_like", and "file_contains_unlike".
353
354       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
360       This program is free software; you can redistribute it and/or modify it
361       under the same terms as Perl itself.
362
363
364
365perl v5.30.1                      2020-01-30                     Test::File(3)
Impressum