Archive-Zip Tests

This document provides some information on writing tests for the Archive::Zip module. Note that the tests have been evolving rather organically over a long time and may contain old-fashioned Perl.

General Guidelines

• To keep test headers somewhat uniform, use a header along the following lines:

  #!/usr/bin/perl
  
  # See https://github.com/redhotpenguin/perl-Archive-Zip/blob/master/t/README.md
  # for a short documentation on the Archive::Zip test infrastructure.
  
  use strict;
  
  BEGIN { $^W = 1; }
  
  use Test::More;
  
  use Archive::Zip qw();
  
  use lib 't';
  use common;
  

• Use BEGIN { $^W = 1; } in the test headers instead of the usually preferred use warnings; since that way the Archive::Zip module itself and its descendants get executed with warnings, too. Which, unfortunately, otherwise would not be the case.

• Keep test data below directory t/data without any additional subdirectories and access it by means of function dataPath.

• Create temporary results only in directory TESTDIR and in files INPUTZIP and OUTPUTZIP to avoid race conditions when tests are executed in parallel. Access directory TESTDIR and any paths below it by means of function testPath.

Constants Provided by Package common

Package common, included by use lib 't'; use common; in a test header, provides the following constants (which are all exported by default):

• TESTDIR

  Relative path to a unique (per test program) temporary test directory located below the build directory of this module. Better use function testPath to access that directory than this constant.

• INPUTZIP, OUTPUTZIP

  Absolute paths to unique (per test program) temporary files with extension .zip that could be used arbitrarily by tests. Except above facts tests should assume nothing about these files.

• TESTSTRING, TESTSTRINGLENGTH, TESTSTRINGCRC

  A somewhat harmless, ASCII-only-but-multi-line test string, its length, and CRC.

• PATH_REL, PATH_ABS, PATH_ZIPFILE, PATH_ZIPDIR, PATH_ZIPABS

  Enumerators used by functions dataPath and testPath, which see.

Functions Provided by Package common

Package common provides the following auxilliary functions (which are all exported by default):

• passThrough( $fromFile, $toFile, $action );

  Reads archive $fromFile, executes $action on every member (or does nothing if $action is false), writes the resulting archive to $toFile.

• my $data = readFile( $file );

  The ubiquitous file slurping function.

• my ( $outErr, $exitVal ) = execProc( $command );

  The likewise ubiquitous process execution function. Even if this function is exceedingly simple, please use it in favor of direct qx{...} or other constructs to have one consistent API.

• my ( $outErr, $exitVal ) = execPerl( @args );

  Executes the Perl running the current test program with the specified arguments.

• my $file = dataPath( "simple" );
my $file = dataPath( "simple.zip" );
my $file = dataPath( "t/data/simple.zip" );

  Returns the path to the specified file below the t/data directory located below the build directory of this module ...

  my $file = dataPath( "simple.zip", PATH_REL );

  ... relative to the build directory with OS-specific path item separators (the default),

  my $file = dataPath( "simple.zip", PATH_ABS );

  ... as absolute path with OS-specific path item separators,

  my $file = dataPath( "simple.zip", PATH_ZIPFILE );

  ... relative to the build directory in Zip (internal) file name format, that is, always with forward slashes as path item separators,

  my $file = dataPath( "simple.zip", PATH_ZIPDIR );

  ... relative to the build directory in Zip (internal) file name format and with a final trailing slash,

  my $file = dataPath( "simple.zip", PATH_ZIPABS );

  ... as absolute path but with any volume specifier stripped and in Zip (internal) file name format.

• my $file = testPath( @pathItems, $pathType );

  Returns the path to the specified file below the directory denoted by TESTDIR in the format specified by the optional path type, which is one of PATH_REL (the default), PATH_ABS, PATH_ZIPFILE, PATH_ZIPDIR, or PATH_ZIPABS, see above.

Test Functions Provided by Package common

Package common provides below test functions (which are all exported by default). "Test functions" means that these functions generate valid TAP and could (and should) be used instead of Test::More functions where appropriate.

Note that some of the test functions rely on a particular $Archive::Zip::Errorhandler being in place, so avoid using your own handler unless you know what you are doing.

As usual, specification of the test name is optional.

• azbinis( $got, $expected, $name );

  Test that succeeds like is from Test::More, but which provides additional diagnostics when comparison of lengthy binary $got and $expected fails. Does not return any meaningful value.

• my $ok = azok( $status, $name );

  Test that succeeds if $status equals AZ_OK and fails otherwise. Provides built-in diagnostics in case of test failure and returns the test verdict.

• my $ok = azis( $status, $expectedStatus, $name );
my $ok = azis( $status, qr/$errorMatchingRegexp/, $name );
my $ok = azis( $status, $expectedStatus, qr/$errorMatchingRegexp/, $name );

  Test that succeeds if the specified status equals the expected status (one of the :ERROR_CODES constants) and/or, if an error has been generated, if the error message matches the specified regexp. Provides built-in diagnostics in case of test failure and returns the test verdict.

• my $fileHandle = azopen( $file )

  Creates and returns a file handle to write to the specified file (defaulting to OUTPUTZIP). If possible, a piped file handle, otherwise a regular one. Returns the undefined value on failure.

• my $ok = azuztok( [['file' =>] $file,]
                    ['name'  => $name] );
  

  Test that succeeds if unzip -t on the specified file (defaulting to OUTPUTZIP) returns exit value zero. This function provides built-in diagnostics in case of test failure and returns the test verdict regardless of the specific calling syntax.

• my $ok = azuztok( [['file' =>] $file,]
                    'refzip' => $refzip,
                    ['name'  => $name] );
  

  Test that succeeds if unzip -t on the specified file returns the same exit value as unzip -t on the specified reference zip file.

• my $ok = azuztok( [['file' =>] $file,]
                    'xppats' => $xppats,
                    ['name'  => $name] );
  

  Test that succeeds depending on the exit value of unzip -t on the specified file, its STDOUT and STDERR, and the operating system the test is running on.

  The expected patterns $xppats must be specified as a list of triples [$exitVal, $outerrRegexp, $osName], like this:

  my $ok = azuztok( "emptyzip.zip",
                    'xppats' => [[0,     undef,         'freebsd'],
                                 [0,     undef,         'netbsd'],
                                 [undef, qr/\bempty\b/, undef]] );
  

  Meaning: Expect exit value zero on FreeBSD and NetBSD (disregarding STDOUT and STDERR on these), and expect STDOUT and STDERR matching /\bempty\b/ on all other operating systems (disregarding exit value on these).

• azwok( $zip, %params )

  Test (actually 6 of them) that succeeds if the specified archive can be written (both using a plain and a piped file handle) and tested using unzip -t.

  Accepts a hash of optional parameters file, refzip, xppats, name, which are processed as explained for function azuztok. Does not return any meaningful value.