Provided by: libtest-cmd-perl_1.05-9_all bug

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