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

Name

6       Test::File::Contents - Test routines for examining the contents of
7       files
8

Synopsis

10         use Test::File::Contents;
11
12         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

Description

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

Interface

26   Options
27       These test functions take an optional hash reference of options which
28       may include one or more of these options:
29
30       "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
38           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
45             use utf8;
46
47           In your test file and write it all in "UTF-8". For example:
48
49             use utf8;
50             use Test::More tests => 1;
51             use Test::File::Contents;
52
53             file_contents_eq('utf8.txt',   'aaaaaa', { encoding => 'UTF-8' });
54             file_contents_eq('latin1.txt', 'aaaaaa', { encoding => 'UTF-8' });
55
56       "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
60           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
70   Test Functions
71       file_contents_eq
72
73         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
77       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
81       "encoding"
82
83       The old name for this function, "file_contents_is", remains as an
84       alias.
85
86       file_contents_eq_or_diff
87
88         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
92       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
98       "encoding"
99       "style"
100       "context"
101
102       file_contents_ne
103
104         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
108       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
112       "encoding"
113
114       The old name for this function, "file_contents_isnt", remains as an
115       alias.
116
117       file_contents_like
118
119         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
123       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
127       "encoding"
128
129       file_contents_unlike
130
131         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
135       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
139       "encoding"
140
141       file_md5sum_is
142
143         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
147       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
152       "encoding"
153           Probably not useful unless left unset or set to ":raw".
154
155       The old name for this function, "file_md5sum", remains as an alias.
156
157       files_eq
158
159         files_eq $file1, $file2, $description;
160         files_eq $file1, $file2, { encoding => 'UTF-8' };
161         files_eq $file1, $file2, { encoding => ':bytes' }, $description;
162
163       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
167       "encoding"
168
169       The old name for this function, "file_contents_identical", remains as
170       an alias.
171
172       files_eq_or_diff
173
174         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
178       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
182       "encoding"
183       "style"
184       "context"
185

Authors

187       •   Kirrily Robert <skud@cpan.org>
188
189       •   David E. Wheeler <david@justatheory.com>
190

Support

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
196       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
205       This program is free software; you can redistribute it and/or modify it
206       under the same terms as Perl itself.
207
208
209
210perl v5.34.0                      2021-07-23           Test::File::Contents(3)
Impressum