NAME¶
Test::Cmd::Common - module for common Test::Cmd error handling
SYNOPSIS¶
use Test::Cmd::Common;
$test = Test::Cmd::Common->new(string => 'functionality being tested',
prog => 'program_under_test',
);
$test->run(chdir => 'subdir', fail => '$? != 0',
flags => '-x', targets => '.',
stdout => <<_EOF_, stderr => <<_EOF_);
expected standard output
_EOF_
expected error output
_EOF_
$test->subdir('subdir', ...);
$test->read(\$contents, 'file');
$test->read(\@lines, 'file');
$test->write('file', <<_EOF_);
contents of the file
_EOF_
$test->file_matches();
$test->must_exist('file', ['subdir', 'file'], ...);
$test->must_not_exist('file', ['subdir', 'file'], ...);
$test->copy('src_file', 'dst_file');
$test->chmod($mode, 'file', ...);
$test->sleep;
$test->sleep($seconds);
$test->touch('file', ...);
$test->unlink('file', ...);
DESCRIPTION¶
The "Test::Cmd::Common" module provides a simple, high-level interface
for writing tests of executable commands and scripts, especially commands and
scripts that interact with the file system. All methods throw exceptions and
exit on failure. This makes it unnecessary to add explicit checks for return
values, making the test scripts themselves simpler to write and easier to
read.
The "Test::Cmd::Common" class is a subclass of "Test::Cmd".
In essence, "Test::Cmd::Common" is a wrapper that treats common
"Test::Cmd" error conditions as exceptions that terminate the test.
You can use "Test::Cmd::Common" directly, or subclass it for your
program and add additional (or override) methods to tailor it to your
program's specific needs. Alternatively, "Test::Cmd::Common" serves
as a useful example of how to define your own "Test::Cmd" subclass.
The "Test::Cmd::Common" module provides the following importable
variables:
- $_exe
- The executable file suffix. This value is normally
available as $Config{_exe} in Perl version 5.005 and later. The
"Test::Cmd::Common" module figures it out via other means in
earlier versions.
- $_o
- The object file suffix. This value is normally available
from $Config{_o} in Perl version 5.005 and later. The
"Test::Cmd::Common" module figures it out via other means in
earlier versions.
- $_a
- The library file suffix. This value is normally available
from as $Config{_a} in Perl version 5.005 and later. The
"Test::Cmd::Common" module figures it out via other means in
earlier versions.
- $_so
- The shared library file suffix. This value is normally
available as $Config{_so} in Perl version 5.005 and later. The
"Test::Cmd::Common" module figures it out via other means in
earlier versions.
- $_is_win32
- A Boolean value that reflects whether the current platform
is a Win32 system.
METHODS¶
- "new"
- Creates a new test environment object. Any arguments are
keyword-value pairs that are passed through to the construct method for
the base class from which we inherit our methods (that is, the
"Test::Cmd" class). In the normal case, this should be the
program to be tested and a description of the functionality being tested:
$test = Test::Cmd::Common->new(prog => 'my_program',
string => 'cool new feature');
By default, methods that match actual versus expected output (the
"run", and "file_matches" methods) use an exact match.
Tests that require regular expression matches can specify this on
initialization of the test environment:
$test = Test::Cmd::Common->new(prog => 'my_program',
string => 'cool new feature',
match_sub => \&Test::Cmd::diff_regex);
or by executing the following after initialization of the test environment:
$test->match_sub(\&Test::Cmd::diff_regex);
Creates a temporary working directory for the test environment and changes
directory to it.
Exits NO RESULT if the object can not be created, the temporary working
directory can not be created, or the current directory cannot be changed
to the temporary working directory.
- "run"
- Runs the program under test, checking that the test
succeeded. Arguments are keyword-value pairs that affect the manner in
which the program is executed or the results are evaluated.
chdir => 'subdir'
fail => 'failure condition' # default is '$? != 0'
flags => 'Cons flags'
stderr => 'expected error output'
stdout => 'expected standard output'
targets => 'targets to build'
The test fails if:
-- The specified failure condition is met. The default failure
condition is '$? != 0', i.e. the program exits unsuccesfully.
A not-uncommon alternative is:
$test->run(fail => '$? == 0'); # expect failure
when testing how the program handles errors.
-- Actual standard output does not match expected standard output
(if any). The expected standard output is an array of lines
or a scalar which will be split on newlines.
-- Actual error output does not match expected error output (if
any). The expected error output is an array of lines or a
scalar which will be split on newlines.
This method will test for NO error output by default if no
expected error output is specified (unlike standard output).
The error output test may be explicitly suppressed by
specifying undef as the "expected" error output:
$test->run(stderr => undef);
By default, this method performs an exact match of actual vs. expected
standard output or error output:
$test->run(stdout => <<_EOF_, stderr => _EOF_);
An expected STDOUT line, which must be matched exactly.
_EOF_
One or more expected STDERR lines,
which must be matched exactly.
_EOF_
Tests that require regular expression matches should be executed using a
test environment that calls the "match_sub" method as follows:
$test->match_sub(\&Test::Cmd::diff_regex);
$test->run(stdout => <<_EOF_, stderr => _EOF_);
An expected (STDOUT|standard output) line\.
_EOF_
One or more expected (STDERR|error output) lines,
which may contain (regexes|regular expressions)\.
_EOF_
- "subdir"
- Creates one or more subdirectories in the temporary working
directory. Exits NO RESULT if the number of subdirectories actually
created does not match the number expected. For compatibility with its
superclass method, returns the number of subdirectories actually
created.
- "read"
- Reads the contents of a file, depositing the contents in
the destination referred to by the first argument (a scalar or array
reference). If the file name is not an absolute path name, it is relative
to the temporary working directory. Exits NO RESULT if the file could not
be read for any reason. For compatibility with its superclass method,
returns TRUE on success.
- "write"
- Writes a file with the specified contents. If the file name
is not an absolute path name, it is relative to the temporary working
directory. Exits NO RESULT if there were any errors writing the file. For
compatibility with its superclass method, returns TRUE on success.
$test->write('file', <<_EOF_);
contents of the file
_EOF_
- "file_matches"
- Matches the contents of the specified file (first argument)
against the expected contents. The expected contents are an array of lines
or a scalar which will be split on newlines. By default, each expected
line must match exactly its corresponding line in the file:
$test->file_matches('file', <<_EOF_);
Line #1.
Line #2.
_EOF_
Tests that require regular expression matches should be executed using a
test environment that calls the "match_sub" method as follows:
$test->match_sub(\&Test::Cmd::diff_regex);
$test->file_matches('file', <<_EOF_);
The (1st|first) line\.
The (2nd|second) line\.
_EOF_
- "must_exist"
- Ensures that the specified files must exist. Files may be
specified as an array reference of directory components, in which case the
pathname will be constructed by concatenating them. Exits FAILED if any of
the files does not exist.
- "must_not_exist"
- Ensures that the specified files must not exist. Files may
be specified as an array reference of directory components, in which case
the pathname will be constructed by concatenating them. Exits FAILED if
any of the files exists.
- "copy"
- Copies a file from the source (first argument) to the
destination (second argument). Exits NO RESULT if the file could not be
copied for any reason.
- "chmod"
- Changes the permissions of a list of files to the specified
mode (first argument). Exits NO RESULT if any file could not be changed
for any reason.
- "sleep"
- Sleeps at least the specified number of seconds. If no
number is specified, sleeps at least a minimum number of seconds necessary
to advance file time stamps on the current system. Sleeping more seconds
is all right. Exits NO RESULT if the time slept was less than
specified.
- "touch"
- Updates the access and modification times of the specified
files. Exits NO RESULT if any file could not be modified for any
reason.
- "unlink"
- Removes the specified files. Exits NO RESULT if any file
could not be removed for any reason.
ENVIRONMENT¶
The "Test::Cmd::Common" module also uses the "PRESERVE",
"PRESERVE_FAIL", "PRESERVE_NO_RESULT", and
"PRESERVE_PASS" environment variables from the "Test::Cmd"
module. See the "Test::Cmd" documentation for details.
SEE ALSO¶
perl(1),
Test::Cmd(3).
The most involved example of using the "Test::Cmd::Common" module to
test a real-world application is the "cons-test" testing suite for
the Cons software construction utility. The suite sub-classes
"Test::Cmd::Common" to provide common, application-specific
infrastructure across a large number of end-to-end application tests. The
suite, and other information about Cons, is available at:
http://www.dsmit.com/cons
AUTHOR¶
Steven Knight, knight@baldmt.com
ACKNOWLEDGEMENTS¶
Thanks to Johan Holmberg for asking the question that led to the creation of
this package.
The general idea of testing commands in this way, as well as the test reporting
of the "pass", "fail" and "no_result" methods,
come from the testing framework invented by Peter Miller for his Aegis project
change supervisor. Aegis is an excellent bit of work which integrates creation
and execution of regression tests into the software development process.
Information about Aegis is available at:
http://www.tip.net.au/~millerp/aegis.html