Test::Cmd 1.05

Test::Cmd is a Perl module for portable testing of commands and scripts.

SYNOPSIS

use Test::Cmd;

$test = Test::Cmd->new(prog => program_or_script_to_test,
interpreter => script_interpreter,
string => identifier_string,
workdir => ,
subdir => dir,
match_sub => $code_ref,
verbose => 1);

$test->verbose(1);

$test->prog(program_or_script_to_test);

$test->basename(@suffixlist);

$test->interpreter(script_interpreter);

$test->string(identifier string);

$test->workdir(prefix);

$test->workpath(subdir, file);

$test->subdir(subdir, ...);
$test->subdir([sub, dir], ...);

$test->write(file, <<EOF);
contents of file
EOF
$test->write([subdir, file], <<EOF);
contents of file
EOF

$test->read($contents, file);
$test->read(@lines, file);
$test->read($contents, [subdir, file]);
$test->read(@lines, [subdir, file]);

$test->writable(dir);
$test->writable(dir, $rwflag);
$test->writable(dir, $rwflag, %errors);

$test->preserve(condition, ...);

$test->cleanup(condition);

$test->run(prog => program_or_script_to_test,
interpreter => script_interpreter,
chdir => dir, args => arguments, stdin => <<EOF);
input to program
EOF

$test->pass(condition);
$test->pass(condition, &func);

$test->fail(condition);
$test->fail(condition, &func);
$test->fail(condition, &func, $caller);

$test->no_result(condition);
$test->no_result(condition, &func);
$test->no_result(condition, &func, $caller);

$test->stdout;
$test->stdout($run_number);

$test->stderr;
$test->stderr($run_number);

$test->match(@lines, @matches);
$test->match($lines, $matches);

$test->match_exact(@lines, @matches);
$test->match_exact($lines, $matches);

$test->match_regex(@lines, @regexes);
$test->match_regex($lines, $regexes);

$test->diff_exact(@lines, @matches, @output);
$test->diff_exact($lines, $matches, @output);

$test->diff_regex(@lines, @regexes, @output);
$test->diff_regex($lines, $regexes, @output);

sub func {
my ($self, $lines, $matches) = @_;
# code to match $lines and $matches
}
$test->match_sub(&func);
$test->match_sub(sub { code to match $_[1] and $_[2] });

$test->here;

The Test::Cmd module provides a low-level framework for portable automated testing of executable commands and scripts (in any language, not just Perl), especially commands and scripts that interact with the file system.

The Test::Cmd module makes no assumptions about what constitutes a successful or failed test. Attempting to read a file that doesnt exist, for example, may or may not be an error, depending on the software being tested.

Consequently, no Test::Cmd methods (including the new() method) exit, die or throw any other sorts of exceptions (but they all do return useful error indications). Exceptions or other error status should be handled by a higher layer: a subclass of Test::Cmd, or another testing framework such as the Test or Test::Simple Perl modules, or by the test itself.
(That said, see the Test::Cmd::Common module if you want a similar module that provides exception handling, either to use directly in your own tests, or as an example of how to use Test::Cmd.)

In addition to running tests and evaluating conditions, the Test::Cmd module manages and cleans up one or more temporary workspace directories, and provides methods for creating files and directories in those workspace directories from in-line data (that is, here-documents), allowing tests to be completely self-contained. When used in conjunction with another testing framework, the Test::Cmd module can function as a fixture (common startup code for multiple tests) for simple management of command execution and temporary workspaces.

The Test::Cmd module inherits File::Spec methods (file_name_is_absolute(), catfile(), etc.) to support writing tests portably across a variety of operating and file systems.

A Test::Cmd environment object is created via the usual invocation:

$test = Test::Cmd->new();

Arguments to the Test::Cmd::new method are keyword-value pairs that may be used to initialize the object, typically by invoking the same-named method as the keyword.