| Test::Cmd::Common(3pm) | User Contributed Perl Documentation | Test::Cmd::Common(3pm) |
Test::Cmd::Common - module for common Test::Cmd error handling
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', ...);
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:
$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.
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_
$test->write('file', <<_EOF_);
contents of the file
_EOF_
$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_
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.
perl(1), Test::Cmd.
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
Steven Knight, knight@baldmt.com
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
| 2015-10-25 | perl v5.20.2 |