NAME

Test::Files - A Test::Builder <https://metacpan.org/pod/Test::Builder> based module to ease testing with files and dirs.

In general, the following can be tested:

• If the contents of the file being tested match the expected pattern.
• If the file being tested is identical to the expected file in regard to contents, or size, or existence. If necessary, some parts of the contents can be excluded from the comparison.
• If the directory being tested contains all expected files.
• If the files in the directory being tested are identical to the files in the reference directory in regard to contents, or size, or existence. If necessary, some files as well as some parts of contents can be excluded from the comparison.
• If all files in the directory being tested fulfill certain requirements.

SYNOPSIS

All examples listed below can be found and executed using xt/synopsis.t.

  use Path::Tiny qw( path );
  use Test::Files;
  my $got_file       = path( 'path' )->child( qw( got file ) );
  my $reference_file = path( 'path' )->child( qw( reference file ) );
  my $got_dir        = path( 'path' )->child( qw( got dir ) );
  my $reference_dir  = path( 'path' )->child( qw( reference dir with some stuff ) );
  my @file_list      = qw( expected file );
  my ( $content_check, $expected, $filter, $options );
  plan( 22 );
  # Simply compares file contents to a string:
  $expected = "contents\nof file";
  file_ok( $got_file, $expected, 'got file has expected contents' );
  # Two identical variants comparing file contents
  # to a string ignoring differences in time stamps:
  $expected = "filtered contents\nof file\ncreated at 00:00:00";
  $filter   = sub {
    shift =~ s{ \b (?: [01] \d | 2 [0-3] ) : (?: [0-5] \d ) : (?: [0-5] \d ) \b }
              {00:00:00}grx
  };
  $options  = { FILTER => $filter };
  file_ok       (
    $got_file, $expected, $options,
    "'$got_file' has contents expected after filtering"
  );
  file_filter_ok(
    $got_file, $expected, $filter,
    "'$got_file' has contents expected after filtering"
  );
  # Simply compares two file contents:
  compare_ok( $got_file, $reference_file, 'files are the same' );
  # Two identical variants comparing contents of two files
  # ignoring differences in time stamps:
  $filter  = sub {
    shift =~ s{ \b (?: [01] \d | 2 [0-3] ) : (?: [0-5] \d ) : (?: [0-5] \d ) \b }
              {00:00:00}grx
  };
  $options = { FILTER => $filter };
  compare_ok       (
    $got_file, $reference_file, $options, 'files are almost the same'
  );
  compare_filter_ok(
    $got_file, $reference_file, $filter,  'files are almost the same'
  );
  # Verifies if both got file and reference file exist:
  $options = { EXISTENCE_ONLY => 1 };
  compare_ok( $got_file, $reference_file, $options, 'both files exist' );
  # Verifies if got file and reference file have identical size:
  $options = { SIZE_ONLY => 1 };
  compare_ok(
    $got_file, $reference_file, $options, 'both files have identical size'
  );
  # Verifies if the directory has all expected files (not recursively!):
  $expected = [ qw( files got_dir must contain ) ];
  dir_contains_ok( $got_dir, $expected, 'directory has all files in list' );
  # Two identical variants doing the same verification as before,
  # but additionally verifying if the directory has nothing
  # but the expected files (not recursively!):
  $options = { SYMMETRIC => 1 };
  dir_contains_ok     (
    $got_dir, $expected, $options, 'directory has exactly the files in the list'
  );
  dir_only_contains_ok(
    $got_dir, $expected,           'directory has exactly the files in the list'
  );
  # The same as before, but recursive:
  $options = { RECURSIVE => 1, SYMMETRIC => 1 };
  dir_contains_ok(
    $got_dir, $expected, $options,
    'directory and its subdirectories have exactly the files in the list'
  );
  # The same as before, but ignoring files,
  # which names do not match the required pattern (file "must" will be skipped):
  $options = { NAME_PATTERN => '^[cfg]', RECURSIVE => 1, SYMMETRIC => 1 };
  dir_contains_ok(
    $got_dir, $expected, $options,
    'directory and its subdirectories ' .
    "have exactly the files in the list except of file 'must'"
  );
  # Compares two directories by comparing file contents (not recursively!):
  compare_dirs_ok(
    $got_dir, $reference_dir,
    "all files from '$got_dir' are the same in '$reference_dir' " .
    '(same names, same contents), subdirs are skipped'
  );
  # The same as before, but subdirectories are considered, too:
  $options = { RECURSIVE => 1 };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' and its subdirs are the same in '$reference_dir'"
  );
  # The same as before, but only file sizes are compared:
  $options = { RECURSIVE => 1, SIZE_ONLY => 1 };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' and its subdirs have same sizes in '$reference_dir'"
  );
  # The same as before, but only file existence is verified:
  $options = { EXISTENCE_ONLY => 1, RECURSIVE => 1 };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' and its subdirs exist in '$reference_dir'"
  );
  # The same as before, but only files with base names starting with 'A' are considered:
  $options = { EXISTENCE_ONLY => 1, NAME_PATTERN => '^A', RECURSIVE => 1 };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' and its subdirs " .
    "with base names starting with 'A' exist in '$reference_dir'"
  );
  # The same as before, but the symmetric verification is requested:
  $options = {
    EXISTENCE_ONLY => 1,
    NAME_PATTERN   => '^A',
    RECURSIVE      => 1,
    SYMMETRIC      => 1,
  };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' and its subdirs with base names " .
    "starting with 'A' exist in '$reference_dir' and vice versa"
  );
  # Two identical variants of comparison of two directories by file contents,
  # whereas these contents are first filtered
  # so that time stamps in form of 'HH:MM:SS' are replaced by '00:00:00'
  # like in examples for file_filter_ok and compare_filter_ok:
  $filter  = sub {
    shift =~ s{ \b (?: [01] \d | 2 [0-3] ) : (?: [0-5] \d ) : (?: [0-5] \d ) \b }
              {00:00:00}grx
  };
  $options = { FILTER => $filter };
  compare_dirs_ok(
    $got_dir, $reference_dir, $options,
    "all files from '$got_dir' are the same in '$reference_dir', " .
    'subdirs are skipped, differences of time stamps ignored'
  );
  compare_dirs_filter_ok(
    $got_dir, $reference_dir, $filter,
    "all files from '$got_dir' are the same in '$reference_dir', " .
    'subdirs are skipped, differences of time stamps ignored'
  );
  # Verifies if all plain files in directory and its subdirectories
  # contain the word 'good' (take into consideration the -f test below
  # excluding special files from comparison!):
  $content_check = sub {
    my ( $file ) = @_;
    ! -f $file or path( $file )->slurp =~ / \b good \b /x;
  };
  $options       = { RECURSIVE => 1 };
  find_ok(
    $got_dir, $content_check, $options,
    "all files from '$got_dir' and subdirectories contain the word 'good'"
  );

DESCRIPTION

This module is like Test2::V0 <https://metacpan.org/pod/Test2::V0> or Test::Expander <https://metacpan.org/pod/Test::Expander>, in fact you should use that first as shown above. It supports comparison of files and directories in different ways.

Any file or directory passed to functions of this module can be both a string or an object of Path::Tiny <https://metacpan.org/pod/Path::Tiny>.

Though the test names i.e. the last parameter of every function is optional, you should provide a name of each test for a better maintainability.

You should follow the lead of the "SYNOPSIS" examples and use Path::Tiny <https://metacpan.org/pod/Path::Tiny> or, if you prefer, File::Spec <https://metacpan.org/pod/File::Spec>. This makes it much more likely that your tests will pass on a different operating system.

All of the contents comparison routines provide diff diagnostic output when they report failure. The diff output style can be changed using the option STYLE (see below).

The filter function receives each line of each file. It may perform any necessary transformations (like excising dates), then it must return the line in (possibly) transformed state. For example, the first filter of Phil Crow <https://metacpan.org/author/PHILCROW>, the creator of this module was

  sub chop_dates {
    my $line = shift;
    $line =~ s/\d{4}(.\d\d){5}//g;
    return $line;
  }

This removes all strings like 2003.10.14.14.17.37. Everything else is unchanged and failing tests started passing when they should. If you want to exclude the line from consideration, return empty string or undef.

SEE ALSO

Consult Test::Simple <https://metacpan.org/pod/Test::Simple>, Test2::V0 <https://metacpan.org/pod/Test2::V0>, and Test::Builder <https://metacpan.org/pod/Test::Builder> for more testing help. This module really just adds functions to what Test2::V0 <https://metacpan.org/pod/Test2::V0> does. As recommended by the author of Test::More <https://metacpan.org/pod/Test::More> and Test2::V0 <https://metacpan.org/pod/Test2::V0>, the latter module should be preferred, that's why Test::More <https://metacpan.org/pod/Test::More> is not listed in "SYNOPSIS".

BUGS

Please report any bugs or feature requests through the web interface at <https://github.com/jsf116/Test-Files/issues>.

CAVEATS

Although this module can cope with binary files, too, confirming their equality, but in case of differences a proper representation of comparison results is not guaranteed.

AUTHOR

Phil Crow, <philcrow2000@yahoo.com>

Jurij Fajnberg, <fajnbergj@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2003-2007 by Phil Crow

Copyright 2020-2024 by Jurij Fajnberg

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