Test::F...ontents(3)

💖 NAME 💖

okay bestie, welcome to the Test::F...ontents(3) page — yep, that's the whole truncated title, and it comes from User Contributed Perl Documentation (the header says the name twice, iconic). The actual module is Test::File::Contents, and it's here for one glorious job: Test routines for examining the contents of files. 💅

🚀 SYNOPSIS 🚀

use it like this, no cap:

use Test::File::Contents;

file_contents_eq         $file,  $string,  $description;
file_contents_eq_or_diff $file,  $string,  $description;
file_contents_like       $file,  qr/foo/,  $description;
file_md5sum_is           $file,  $md5sum,  $description;
files_eq                 $file1, $file2,   $description;
files_eq_or_diff         $file1, $file2,   $description;

🌸 DESCRIPTION 🌸

Got an app that generates files? bestie, then you literally need to test those files and make sure their contents are correct. This module makes that easy. Use its test functions to make sure the contents of files are exactly what you expect them to be. periodt. ✨

🧚 INTERFACE 🧚

🎀 Options 🎀

These test functions take an optional hash reference of options, and that hash may include one or more of these cuties:

• encoding — the encoding in which the file is encoded. This gets used in an I/O layer to read the file so it can be properly decoded to Perl's internal representation. Examples include UTF-8, iso-8859-3, and cp1252. See Encode::Supported for a list of supported encodings. It may also be specified as a layer, such as :utf8 or :raw. See perlio for a complete list of layers.

Note that it's important to specify the encoding if you have non-ASCII characters in your file. And the value to be compared against (the string argument to file_contents_eq() and the regular expression argument to file_contents_like(), for example) must be decoded to Perl's internal form. The simplest way to do it is to put use utf8; in your test file and write it all in UTF-8. For example:

use utf8;
use Test::More tests => 1;
use Test::File::Contents;

file_contents_eq('utf8.txt',   'ååå', { encoding => 'UTF-8' });
file_contents_eq('latin1.txt', 'ååå', { encoding => 'UTF-8' });

• style — the style of diff to output in the diagnostics in the case of a failure in file_contents_eq_or_diff. The possible values are:
  • Unified
  • Context
  • OldStyle
  • Table
• context — determines the amount of context displayed in diagnostic diff output. If you need to seem more of the area surrounding different lines, pass this option to determine how many more links you'd like to see. (yes, the original says links — I'm just the messenger 💀)

🧪 Test Functions 🧪

file_contents_eq

file_contents_eq $file, $string, $description;
file_contents_eq $file, $string, { encoding => 'UTF-8' };
file_contents_eq $file, $string, { encoding => ':bytes' }, $description;

Checks that the file's contents are equal to a string. Pass in a Unix-style file name and it will be converted for the local file system. Supported options: encoding.

The old name for this function, file_contents_is, remains as an alias. 🫶

file_contents_eq_or_diff

file_contents_eq_or_diff $file, $string, $description;
file_contents_eq_or_diff $file, $string, { encoding => 'UTF-8' };
file_contents_eq_or_diff $file, $string, { style    => 'context' }, $description;

Like file_contents_eq(), only in the event of failure, the diagnostics will contain a diff instead of the full contents of the file. This can make it easier to test the contents of very large text files, and where only a subset of the lines are different. Supported options: encoding, style, context.

file_contents_ne

file_contents_ne $file, $string, $description;
file_contents_ne $file, $string, { encoding => 'UTF-8' };
file_contents_ne $file, $string, { encoding => ':bytes' }, $description;

Checks that the file's contents do not equal a string. Pass in a Unix-style file name and it will be converted for the local file system. Supported options: encoding.

The old name for this function, file_contents_isnt, remains as an alias. 🫶

file_contents_like

file_contents_like $file, qr/foo/, $description;
file_contents_like $file, qr/foo/, { encoding => 'UTF-8' };
file_contents_like $file, qr/foo/, { encoding => ':bytes' }, $description;

Checks that the contents of a file match a regular expression. The regular expression must be passed as a regular expression object created by qr//. Supported options: encoding.

file_contents_unlike

file_contents_unlike $file, qr/foo/, $description;
file_contents_unlike $file, qr/foo/, { encoding => 'UTF-8' };
file_contents_unlike $file, qr/foo/, { encoding => ':bytes' }, $description;

Checks that the contents of a file do not match a regular expression. The regular expression must be passed as a regular expression object created by qr//. Supported options: encoding.

file_md5sum_is

file_md5sum_is $file, $md5sum, $description;
file_md5sum_is $file, $md5sum, { encoding => 'UTF-8' };
file_md5sum_is $file, $md5sum, { encoding => ':bytes' }, $description;

Checks whether a file matches a given MD5 checksum. The checksum should be provided as a hex string, for example, 6df23dc03f9b54cc38a0fc1483df6e21. Pass in a Unix-style file name and it will be converted for the local file system. Supported options:

• encoding — Probably not useful unless left unset or set to :raw.

The old name for this function, file_md5sum, remains as an alias. 🫶

files_eq

files_eq $file1, $file2, $description;
files_eq $file1, $file2, { encoding => 'UTF-8' };
files_eq $file1, $file2, { encoding => ':bytes' }, $description;

Tests that the contents of two files are the same. Pass in a Unix-style file name and it will be converted for the local file system. Supported options: encoding.

The old name for this function, file_contents_identical, remains as an alias. 🫶

files_eq_or_diff

files_eq_or_diff $file1, $file2, $description;
files_eq_or_diff $file1, $file2, { encoding => 'UTF-8' };
files_eq_or_diff $file1, $file2, { style    => 'context' }, $description;

Like files_eq(), this function tests that the contents of two files are the same. Unlike files_eq(), on failure this function outputs a diff of the two files in the diagnostics. Supported options: encoding, style, context.

👑 AUTHOR 👑

• Kirrily Robert
• David E. Wheeler

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2016 by David E. Wheeler.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

---

mwah 💋 — source/version: perl v5.42.0, date: 2022-09-02, page: Test::F...ontents(3). byeeee 🫶