1Test::File::Contents(3)User Contributed Perl DocumentatioTnest::File::Contents(3)
2
6 Test::File::Contents - Test routines for examining the contents of
7 files
8
10 use Test::File::Contents;
11 file_contents_eq $file, $string, $description;
13 file_contents_eq_or_diff $file, $string, $description;
14 file_contents_like $file, qr/foo/, $description;
15 file_md5sum_is $file, $md5sum, $description;
16 files_eq $file1, $file2, $description;
17 files_eq_or_diff $file1, $file2, $description;
18
20 Got an app that generates files? Then you need to test those files to
21 make sure that their contents are correct. This module makes that easy.
22 Use its test functions to make sure that the contents of files are
23 exactly what you expect them to be.
24
26 Options
27 These test functions take an optional hash reference of options which
28 may include one or more of these options:
29 "encoding"
31 The encoding in which the file is encoded. This will be used in an
32 I/O layer to read in the file, so that it can be properly decoded
33 to Perl's internal representation. Examples include "UTF-8",
34 "iso-8859-3", and "cp1252". See Encode::Supported for a list of
35 supported encodings. May also be specified as a layer, such as
36 ":utf8" or ":raw". See perlio for a complete list of layers.
37 Note that it's important to specify the encoding if you have non-
39 ASCII characters in your file. And the value to be compared against
40 (the string argument to "file_contents_eq()" and the regular
41 expression argument to "file_contents_like()", for example, must be
42 decoded to Perl's internal form. The simplest way to do so use to
43 put
44 use utf8;
46 In your test file and write it all in "UTF-8". For example:
48 use utf8;
50 use Test::More tests => 1;
51 use Test::File::Contents;
52 file_contents_eq('utf8.txt', 'aaaaaa', { encoding => 'UTF-8' });
54 file_contents_eq('latin1.txt', 'aaaaaa', { encoding => 'UTF-8' });
55 "style"
57 The style of diff to output in the diagnostics in the case of a
58 failure in "file_contents_eq_or_diff". The possible values are:
59 Unified
61 Context
62 OldStyle
63 Table
64 "context"
65 Determines the amount of context displayed in diagnostic diff
66 output. If you need to seem more of the area surrounding different
67 lines, pass this option to determine how many more links you'd like
68 to see.
69 Test Functions
71 file_contents_eq
72 file_contents_eq $file, $string, $description;
74 file_contents_eq $file, $string, { encoding => 'UTF-8' };
75 file_contents_eq $file, $string, { encoding => ':bytes' }, $description;
76 Checks that the file's contents are equal to a string. Pass in a Unix-
78 style file name and it will be converted for the local file system.
79 Supported options:
80 "encoding"
82 The old name for this function, "file_contents_is", remains as an
84 alias.
85 file_contents_eq_or_diff
87 file_contents_eq_or_diff $file, $string, $description;
89 file_contents_eq_or_diff $file, $string, { encoding => 'UTF-8' };
90 file_contents_eq_or_diff $file, $string, { style => 'context' }, $description;
91 Like "file_contents_eq()", only in the event of failure, the
93 diagnostics will contain a diff instead of the full contents of the
94 file. This can make it easier to test the contents of very large text
95 files, and where only a subset of the lines are different. Supported
96 options:
97 "encoding"
99 "style"
100 "context"
101 file_contents_ne
103 file_contents_ne $file, $string, $description;
105 file_contents_ne $file, $string, { encoding => 'UTF-8' };
106 file_contents_ne $file, $string, { encoding => ':bytes' }, $description;
107 Checks that the file's contents do not equal a string. Pass in a Unix-
109 style file name and it will be converted for the local file system.
110 Supported options:
111 "encoding"
113 The old name for this function, "file_contents_isnt", remains as an
115 alias.
116 file_contents_like
118 file_contents_like $file, qr/foo/, $description;
120 file_contents_like $file, qr/foo/, { encoding => 'UTF-8' };
121 file_contents_like $file, qr/foo/, { encoding => ':bytes' }, $description;
122 Checks that the contents of a file match a regular expression. The
124 regular expression must be passed as a regular expression object
125 created by "qr//". Supported options:
126 "encoding"
128 file_contents_unlike
130 file_contents_unlike $file, qr/foo/, $description;
132 file_contents_unlike $file, qr/foo/, { encoding => 'UTF-8' };
133 file_contents_unlike $file, qr/foo/, { encoding => ':bytes' }, $description;
134 Checks that the contents of a file do not match a regular expression.
136 The regular expression must be passed as a regular expression object
137 created by "qr//". Supported options:
138 "encoding"
140 file_md5sum_is
142 file_md5sum_is $file, $md5sum, $description;
144 file_md5sum_is $file, $md5sum, { encoding => 'UTF-8' };
145 file_md5sum_is $file, $md5sum, { encoding => ':bytes' }, $description;
146 Checks whether a file matches a given MD5 checksum. The checksum should
148 be provided as a hex string, for example,
149 "6df23dc03f9b54cc38a0fc1483df6e21". Pass in a Unix-style file name and
150 it will be converted for the local file system. Supported options:
151 "encoding"
153 Probably not useful unless left unset or set to ":raw".
154 The old name for this function, "file_md5sum", remains as an alias.
156 files_eq
158 files_eq $file1, $file2, $description;
160 files_eq $file1, $file2, { encoding => 'UTF-8' };
161 files_eq $file1, $file2, { encoding => ':bytes' }, $description;
162 Tests that the contents of two files are the same. Pass in a Unix-style
164 file name and it will be converted for the local file system. Supported
165 options:
166 "encoding"
168 The old name for this function, "file_contents_identical", remains as
170 an alias.
171 files_eq_or_diff
173 files_eq_or_diff $file1, $file2, $description;
175 files_eq_or_diff $file1, $file2, { encoding => 'UTF-8' };
176 files_eq_or_diff $file1, $file2, { style => 'context' }, $description;
177 Like "files_eq()", this function tests that the contents of two files
179 are the same. Unlike "files_eq()", on failure this function outputs a
180 diff of the two files in the diagnostics. Supported options:
181 "encoding"
183 "style"
184 "context"
185
187 · Kirrily Robert <skud@cpan.org>
188 · David E. Wheeler <david@justatheory.com>
190
192 This module is stored in an open GitHub repository
193 <https://github.com/theory/test-file-contents/>. Feel free to fork and
194 contribute!
195 Please file bug reports via GitHub Issues
197 <https://github.com/theory/test-file-contents/issues/> or by sending
198 mail to bug-Test-File-Contents@rt.cpan.org <mailto:bug-Test-File-
199 Contents@rt.cpan.org>.
200
202 Copyright (c) 2004-2007 Kirrily Robert. Some Rights Reserved.
203 Copyright (c) 2007-2016 David E. Wheeler. Some Rights Reserved.
204 This program is free software; you can redistribute it and/or modify it
206 under the same terms as Perl itself.
207perl v5.32.0 2020-07-28 Test::File::Contents(3)