NAME

test - tools for helping in test suites (not including running externalprograms).

SYNOPSIS

use FindBin               1.42 qw( $Bin );
use Test                  1.13 qw( ok plan );

BEGIN { unshift @INC, $Bin };

use test                  qw( DATA_DIR
                              evcheck runcheck );

BEGIN {
  plan tests  => 3,
       todo   => [],
       ;
}

ok evcheck(sub {
             open my $fh, '>', 'foo';
             print $fh "$_\n"
               for 'Bulgaria', 'Cholet';
             close $fh;
           }, 'write foo'), 1, 'write foo';

save_output('stderr', *STDERR{IO});
warn 'Hello, Mum!';
print restore_output('stderr');

DESCRIPTION

This package provides some variables, and sets up an environment, for test scripts, such as those used in t/.

This package does not including running external programs; that is provided by test2.pm. This is so that suites not needing that can include only test.pm, and so not require the presence of IPC::Run.

Setting up the environment includes:

Prepending blib/script onto the path

Pushing the module lib/ dir onto the @PERL5LIB var

For executed scripts.

Pushing the module lib/ dir onto the @INC var

For internal use calls.

Changing directory to a temporary directory

To avoid cluttering the local dir, and/or allowing the local directory structure to affect matters.

Cleaning up the temporary directory afterwards

Unless TEST_DEBUG is set in the environment.

EXPORTS

The following symbols are exported upon request:

BIN_DIR

DATA_DIR

REF_DIR

LIB_DIR

PERL

check_req

compare

evcheck

only_files

save_output

restore_output

tmpnam

tempdir

find_exec

read_file

only_files

ARGUMENTS

expect

Arrayref of names of files to expect to exist.

RETURNS

ok

1 if exactly expected files exist, false otherwise.

evcheck

Eval code, return status

ARGUMENTS

code

Coderef to eval

name

Name to use in error messages

RETURNS

okay

1 if eval was okay, 0 if not.

save_output

Redirect a filehandle to temporary storage for later examination.

ARGUMENTS

name

Name to store as (used in restore_output)

filehandle

The filehandle to save

restore_output

Restore a saved filehandle to its original state, return the saved output.

ARGUMENTS

name

Name of the filehandle to restore (as passed to save_output).

RETURNS

saved_string

A single string being the output saved.

tmpnam

Very much like the one in POSIX or File::Temp, but does not get deleted if TEST_DEBUG has SAVE in the value.

ARGUMENTS

name

Optional. If defined, a name by which to refer to the tmpfile in user messages.

RETURNS

filename

Name of temporary file.

fh

Open filehandle to temp file, in r/w mode. Only created & returned in list context.

tempdir

Very much like the one in POSIX or File::Temp, but does not get deleted if TEST_DEBUG has SAVE in the value (does get deleted otherwise).

ARGUMENTS

None

RETURNS

name

Name of temporary dir.

compare

compare(+{ fn1 => $fn1, fn2 => $fn2, gzip => 1 });

This performs one test.

ARGUMENTS

A single argument is taken, considered as a hash ref, with the following keys:

In TEST_DEBUG mode, if the files do not compare equal, outputs file info on STDERR.

fn1

Mandatory File to compare

fn2

Mandatory File to compare

name

Mandatory Test name

sort

Optional sort files prior to comparison. Requires the sort command to be on $PATH (else skips).

gunzip

Optional gunzip files prior to comparison. Requires the gzip command to be on $PATH (else skips). gzip occurs prior to any sort.

untar

Optional untar files prior to comparison. Requires the tar command to be on $PATH (else skips). any gzip occurs prior to any tar. Tar files are considered equal if they each contain the same filenames & each file contained is equal. If the sort flag is present, each file is sorted prior to comparison.

check_req

Perform a requisite check on a given executable. This will skip if the required modules are not present.

4+(n+m)*2 tests are performed, where n is the number of prerequisites expected, and m is the number of outputs expected.

SYNOPSIS

check_req('ccu-touch',
          ['/etc/passwd'],
          [[REQ_FILE, '/etc/passwd']],
          [[REQ_FILE, 'passwd.foo']],
          'requisites 1');

ARGUMENTS

cmd_name

The name of the command to run. It is assumed that this command is in blib/script; hence it should be an executable in this package, and make shuold have been run recently.

args

The arguments to pass to the cmd_name, as an arrayref.

epres

The expected prerequisites, as an arrayref, wherein every member is a two-element arrayref, the members being the requisite type, and the requisite value.

eouts

The expected outputs, in the same format as the epres.

testname

The name to use in error messages.

find_exec

ARGUMENTS

proggie

The name of the program

RETURNS

path

The path to the first executable file with the given name on $PATH. Or nothing, if no such file exists.

read_file

ARGUMENTS

filename

Mandatory

line-terminator

Optional. Value of $/. Defaults to "\n".

RETURNS

lines

A list of lines in the file (lines determined by the value of line-terminator), as an arrayref.

EXAMPLES

BUGS

REPORTING BUGS

Email the author.

AUTHOR

Martyn J. Pearce fluffy@cpan.org

COPYRIGHT

Copyright (c) 2001, 2002, 2003 Martyn J. Pearce. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

cpanm Class::MethodMaker

perl -MCPAN -e shell
install Class::MethodMaker