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

NAME

       Test::Cmd - 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;

DESCRIPTION

       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 doesn't 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.

TESTING FRAMEWORKS

       As mentioned, because the "Test::Cmd" module makes no assumptions about what constitutes success or
       failure of a test, it can be used to provide temporary workspaces, other file system interaction, or
       command execution for a variety of testing frameworks.  This section describes how to use the "Test::Cmd"
       with several different higher-layer testing frameworks.

       Note that you should not intermix multiple testing frameworks in a single testing script.

   "Test::Harness"
       The "Test::Cmd" module may be used in tests that print results in a format suitable for the standard Perl
       "Test::Harness" module:

           use Test::Cmd;

           print "1..5\n";

           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
           if ($test) { print "ok 1\n"; } else { print "not ok 1\n"; }

           $input = <<_EOF;
           test_program should process this input
           and exit successfully (status 0).
           _EOF_

           $wrote_file = $test->write('input_file', $input);
           if ($wrote_file) { print "ok 2\n"; } else { print "not ok 2\n"; }

           $test->run(args => '-x input_file');
           if ($? == 0) { print "ok 3\n"; } else { print "not ok 3\n"; }

           $wrote_file = $test->write('input_file', $input);
           if ($wrote_file) { print "ok 4\n"; } else { print "not ok 4\n"; }

           $test->run(args => '-y input_file');
           if ($? == 0) { print "ok 5\n"; } else { print "not ok 5\n"; }

       Several other Perl modules simplify the use of "Test::Harness" by eliminating the need to hand-code the
       "print" statements and test numbers.  The "Test" module, the "Test::Simple" module, and the "Test::More"
       module all export an "ok()" subroutine to test conditions.  Here is how the above example would look
       rewritten to use "Test::Simple":

           use Test::Simple tests => 5;
           use Test::Cmd;

           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
           ok($test, "creating Test::Cmd object");

           $input = <<_EOF;
           test_program should process this input
           and exit successfully (status 0).
           _EOF_

           $wrote_file = $test->write('input_file', $input);
           ok($wrote_file, "writing input_file");

           $test->run(args => '-x input_file');
           ok($? == 0, "executing test_program -x input_file");

           $wrote_file = $test->write('input_file', $input);
           ok($wrote_file, "writing input_file");

           $test->run(args => '-y input_file');
           ok($? == 0, "executing test_program -y input_file");

   "Test::Unit"
       The Perl "Test::Unit" package provides a procedural testing interface modeled after a testing framework
       widely used in the eXtreme Programming development methodology.  The "Test::Cmd" module can function as
       part of a "Test::Unit" fixture that can set up workspaces as needed for a set of tests.  This avoids
       having to repeat code to re-initialize an input file multiple times:

           use Test::Unit;
           use Test::Cmd;

           my $test;

           $input = <<'EOF';
           test_program should process this input
           and exit successfully (status 0).
           EOF

           sub set_up {
               $test = Test::Cmd->new(prog => 'test_program', workdir => '');
               $test->write('input_file', $input);
           }

           sub test_x {
               my $result = $test->run(args => '-x input_file');
               assert($result == 0, "failed test_x\n");
           }

           sub test_y {
               my $result = $test->run(args => '-y input_file');
               assert($result == 0, "failed test_y\n");
           }

           create_suite();
           run_suite;

       Note that, because the "Test::Cmd" module takes care of cleaning up temporary workspaces on exit, there
       is no need to remove explicitly the workspace in a "tear_down" subroutine.  (There may, of course, be
       other things in the test that need a "tear_down" subroutine.)

   Aegis
       Alternatively, the "Test::Cmd" module provides "pass()", "fail()", and "no_result()" methods that can be
       used to provide an appropriate exit status and simple printed indication for a test.  These methods
       terminate the test immediately, reporting "PASSED", "FAILED", or "NO RESULT" respectively, and exiting
       with status 0 (success), 1 or 2 respectively.

       The separate "fail()" and "no_result()" methods allow for a distinction between an actual failed test and
       a test that could not be properly evaluated because of an external condition (such as a full file system
       or incorrect permissions).

       The exit status values happen to match the requirements of the Aegis change management system, and the
       printed strings are based on existing Aegis conventions.  They are not really Aegis-specific, however,
       and provide a simple, useful starting point if you don't already have another testing framework:

           use Test::Cmd;

           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
           Test::Cmd->no_result(! $test);

           $input = <<EOF;
           test_program should process this input
           and exit successfully (status 0).
           EOF

           $wrote_file = $test->write('input_file', $input);
           $test->no_result(! $wrote_file);

           $test->run(args => '-x input_file');
           $test->fail($? != 0);

           $wrote_file = $test->write('input_file', $input);
           $test->no_result(! $wrote_file);

           $test->run(args => '-y input_file');
           $test->fail($? != 0);

           $test->pass;

       Note that the separate "Test::Cmd::Common" wrapper module can simplify the above example even further by
       taking care of common exception handling cases within the testing object itself.

           use Test::Cmd::Common;

           $test = Test::Cmd::Common->new(prog => 'test_program', workdir => '');

           $input = <<EOF;
           test_program should process this input
           and exit successfully (status 0).
           EOF

           $wrote_file = $test->write('input_file', $input);

           $test->run(args => '-x input_file');

           $wrote_file = $test->write('input_file', $input);

           $test->run(args => '-y input_file');

           $test->pass;

       See the "Test::Cmd::Common" module for details.

METHODS

       Methods supported by the "Test::Cmd" module include:

       "new"
           Create  a new "Test::Cmd" environment.  Arguments with which to initialize the environment are passed
           in as keyword-value pairs.  Fails if a specified temporary working directory or  subdirectory  cannot
           be created.  Does NOT die or exit on failure, but returns FALSE if the test environment object cannot
           be created.

       "verbose"
           Sets the verbose level for the environment object to the specified value.

       "prog"
           Specifies  the  executable  program  or  script  to be tested.  Returns the absolute path name of the
           current program or script.

       "basename"
           Returns the basename of the current program or script.  Any specified arguments are a  list  of  file
           suffixes that may be stripped from the basename.

       "interpreter"
           Specifies  the  program  to  be  used  to interpret "prog" as a script.  Returns the current value of
           "interpreter".

       "string"
           Specifies an identifier string for the functionality being tested to be  printed  on  failure  or  no
           result.

       "workdir"
           When an argument is specified, creates a temporary working directory with the specified name.  If the
           argument  is  a NULL string (''), the directory is named "testcmd" by default, followed by the unique
           ID of the executing process.

           Returns the absolute pathname to the temporary working directory, or FALSE if the directory could not
           be created.

       "workpath"
           Returns the absolute path name to  a  subdirectory  or  file  under  the  current  temporary  working
           directory by concatenating the temporary working directory name with the specified arguments.

       "subdir"
           Creates  new  subdirectories under the temporary working dir, one for each argument.  An argument may
           be an array reference, in  which  case  the  array  elements  are  concatenated  together  using  the
           "File::Spec-&"catfile>  method.   Subdirectories  multiple levels deep must be created via a separate
           argument for each level:

               $test->subdir('sub', ['sub', 'dir'], [qw(sub dir ectory)]);

           Returns the number of subdirectories actually created.

       "write"
           Writes the specified text (second argument) to the specified file name (first  argument).   The  file
           name may be an array reference, in which case all the array elements except the last are subdirectory
           names  to  be concatenated together.  The file is created under the temporary working directory.  Any
           subdirectories in the path must already exist.

       "read"
           Reads the contents of the specified file name (second argument) into the scalar or array referred  to
           by the first argument.  The file name may be an array reference, in which case all the array elements
           except  the last are subdirectory names to be concatenated together.  The file is assumed to be under
           the temporary working directory unless it is an absolute path name.

           Returns TRUE on successfully opening and reading the file, FALSE otherwise.

       "writable"
           Makes every file and directory within the specified directory tree writable ("rwflag" == TRUE) or not
           writable ("rwflag" == FALSE).  The default is to make the directory tree writable.  Optionally  fills
           in  the  supplied  hash reference with a hash of path names that could not have their permissions set
           appropriately, with the reason why each could not be set.

       "preserve"
           Arranges for the temporary working directories  for  the  specified  "Test::Cmd"  environment  to  be
           preserved  for  one  or  more conditions.  If no conditions are specified, arranges for the temporary
           working directories to be preserved for all conditions.

       "cleanup"
           Removes any temporary  working  directories  for  the  specified  "Test::Cmd"  environment.   If  the
           environment  variable  "PRESERVE"  was  set when the "Test::Cmd" module was loaded, temporary working
           directories are not removed.  If any of the environment variables  "PRESERVE_PASS",  "PRESERVE_FAIL",
           or  "PRESERVE_NO_RESULT"  were  set  when  the  "Test::Cmd" module was loaded, then temporary working
           directories are not removed if the test passed, failed, or had no  result,  respectively.   Temporary
           working directories are also preserved for conditions specified via the "preserve" method.

           Typically,  this  method  is  not  called  directly,  but  is  used when the script exits to clean up
           temporary working directories as appropriate for the exit status.

       "run"
           Runs a test of the program or script for the test environment.  Standard output and error output  are
           saved for future retrieval via the "stdout" and "stderr" methods.

           Arguments are supplied as keyword-value pairs:

           "args"
               Specifies  the command-line arguments to be supplied to the program or script under test for this
               run:

                       $test->run(args => 'arg1 arg2');

           "chdir"
               Changes directory to the path specified as the value argument:

                       $test->run(chdir => 'xyzzy');

               If the specified path is not an absolute path name (begins with '/' on Unix  systems),  then  the
               subdirectory   is   relative   to   the   temporary   working   directory   for  the  environment
               ("$test-&"workdir>).  Note that, by default,  the  "Test::Cmd"  module  does  NOT  chdir  to  the
               temporary  working  directory,  so to execute the test under the temporary working directory, you
               must specify an explicit "chdir" to the current directory:

                       $test->run(chdir => '.');               # Unix-specific

                       $test->run(chdir => $test->curdir);     # portable

           "interpreter"
               Specifies the program to be used to interpret "prog" as a script, for this run only.   This  does
               not change the "$test-&"interpreter> value of the test environment.

           "prog"
               Specifies  the  executable  program or script to be run, for this run only.  This does not change
               the "$test-&"prog> value of the test environment.

           "stdin"
               Pipes the specified value (string or array ref) to the program or script under test for this run:

                       $test->run(stdin => <<_EOF_);
                       input to the program under test
                       _EOF_

           Returns the exit status of the program or script.

       "pass"
           Exits the test successfully.  Reports "PASSED" on the error output and exits with a status of 0.   If
           a  condition  is  supplied,  only  exits  the  test  if  the condition evaluates TRUE.  If a function
           reference is supplied, executes the function before reporting and exiting.

       "fail"
           Exits the test unsuccessfully.  Reports "FAILED test of {string} at line {line} of  {file}."  on  the
           error  output  and  exits with a status of 1.  If a condition is supplied, only exits the test if the
           condition evaluates TRUE.  If  a  function  reference  is  supplied,  executes  the  function  before
           reporting and exiting.  If a caller level is supplied, prints a simple calling trace N levels deep as
           part of reporting the failure.

       "no_result"
           Exits  the  test  with  an  indeterminate  result  (the  test  could not be performed due to external
           conditions such as, for example, a full file system).  Reports "NO RESULT for  test  of  {string}  at
           line  {line}  of  {file}."  on  the  error  output  and  exits with a status of 2.  If a condition is
           supplied, only exits the test if the condition evaluates TRUE.  If a function reference is  supplied,
           executes  the  function before reporting and exiting.  If a caller level is supplied, prints a simple
           calling trace N levels deep as part of reporting the failure.

       "stdout"
           Returns the standard output from the specified run number.  If there is no specified run number, then
           returns the standard output of the last run.  Returns the standard output as either a  scalar  or  an
           array  of output lines, as appropriate for the calling context.  Returns "undef" if there has been no
           test run.

       "stderr"
           Returns the error output from the specified run number.  If there is no specified  run  number,  then
           returns the error output of the last run.  Returns the error output as either a scalar or an array of
           output lines, as apporpriate for the calling context.  Returns "undef" if there has been no test run.

       "match"
           Matches  one  or  more  input  lines  against  an equal number of expected lines using the currently-
           registered line-matching function.  The default line-matching function is the  "match_regex"  method,
           which means that the default is to match lines against regular expressions.

       "match_exact"
           Compares  two  arrays  of lines for exact matches.  The arguments are passed in as either scalars, in
           which case each is split on newline boundaries, or as array references.  An unequal number  of  lines
           in the two arrays fails immediately and returns FALSE before any comparisons are performed.

           Returns TRUE if each line matched its corresponding line in the other array, FALSE otherwise.

       "match_regex"
           Matches  one  or  more input lines against an equal number of regular expressions.  The arguments are
           passed in as either scalars, in which  case  each  is  split  on  newline  boundaries,  or  as  array
           references.  Trailing newlines are stripped from each line and regular expression.  An unequal number
           of  lines  and  regular  expressions  fails  immediately and returns FALSE before any comparisons are
           performed.  Comparison is performed for each entire line,  that  is,  with  each  regular  expression
           anchored at both the start of line (^) and end of line ($).

           Returns TRUE if each line matched each regular expression, FALSE otherwise.

       "diff_exact"
           Diffs two arrays of lines in a manner similar to the UNIX diff(1) utility.

           If  the  "Algorithm::DiffOld"  package  is  installed  on  the  local  system,  output describing the
           differences between the input lines and the matching lines,  in  diff(1)  format,  is  saved  to  the
           $output  array  reference.   In  the  diff output, the expected output lines are considered the "old"
           (left-hand) file, and the actual output is considered the "new" (right-hand) file.

           If the "Algorithm::DiffOld" package is not installed on the local system,  the  Expected  and  Actual
           contents are saved as-is to the $output array reference.

           The  "lines"  and "matches" arguments are passed in as either scalars, in which case each is split on
           newline boundaries, or as array references.  Trailing  newlines  are  stripped  from  each  line  and
           regular expression.

           Returns TRUE if each line matched its corresponding line in the expected matches, FALSE otherwise, in
           order to conform to the conventions of the "match" method.

           Typical invocation:

                   if (! $test->diff_exact($test->stdout,
                                           \@expected_lines,
                                           \@diff)) {
                           print @diff;
                   }

       "diff_regex"
           Diffs one or more input lines against one or more regular expressions in a manner similar to the UNIX
           diff(1) utility.

           If  the  "Algorithm::DiffOld"  package  is  installed  on  the  local  system,  output describing the
           differences between the input lines and the matching lines,  in  diff(1)  format,  is  saved  to  the
           $output  array  reference.   In  the  diff output, the expected output lines are considered the "old"
           (left-hand) file, and the actual output is considered the "new" (right-hand) file.

           If the "Algorithm::DiffOld" package is not installed on the local system,  the  Expected  and  Actual
           contents are saved as-is to the $output array reference.

           The  "lines"  and "regexes" arguments are passed in as either scalars, in which case each is split on
           newline boundaries, or as array references.  Trailing  newlines  are  stripped  from  each  line  and
           regular  expression.   Comparison  is  performed  for  each  entire  line, that is, with each regular
           expression anchored at both the start of line (^) and end of line ($).

           Returns TRUE if each line matched each regular expression, FALSE otherwise, in order  to  conform  to
           the conventions of the "match" method.

           Typical invocation:

                   if (! $test->diff_regex($test->stdout,
                                           \@expected_lines,
                                           \@diff)) {
                           print @diff;
                   }

       "match_sub"
           Registers  the  specified  code  reference  as the line-matching function to be called by the "match"
           method.  This can be a user-supplied subroutine, or the "match_exact",  "match_regex",  "diff_exact",
           or "diff_regex" methods supplied by the "Test::Cmd" module:

                   $test->match_sub(\&Test::Cmd::match_exact);

                   $test->match_sub(\&Test::Cmd::match_regex);

                   $test->match_sub(\&Test::Cmd::diff_exact);

                   $test->match_sub(\&Test::Cmd::diff_regex);

           The  "match_exact", "match_regex", "diff_exact" and "diff_regex" subroutine names are exportable from
           the "Test::Cmd" module, and may be specified at object initialization:

                   use Test::Cmd qw(match_exact match_regex diff_exact diff_regex);
                   $test_exact = Test::Cmd->new(match_sub => \&match_exact);
                   $test_regex = Test::Cmd->new(match_sub => \&match_regex);
                   $test_exact = Test::Cmd->new(match_sub => \&diff_exact);
                   $test_regex = Test::Cmd->new(match_sub => \&diff_regex);

       "here"
           Returns the absolute path name of the current working directory.  (This is essentially  the  same  as
           the  "Cwd::cwd"  method,  except that the "Test::Cmd::here" method preserves the directory separators
           exactly as returned by the  underlying  operating-system-dependent  method.   The  "Cwd::cwd"  method
           canonicalizes  all  directory separators to '/', which makes for consistent path name representations
           within Perl, but may mess up another program or script to which you try to pass the path name.)

ENVIRONMENT

       Several environment variables affect the default  values  in  a  newly  created  "Test::Cmd"  environment
       object.   These  environment  variables  must  be  set  when the module is loaded, not when the object is
       created.

       "PRESERVE"
           If set to a true value, all temporary working directories will be preserved on  exit,  regardless  of
           success  or  failure  of  the test.  The full path names of all temporary working directories will be
           reported on error output.

       "PRESERVE_FAIL"
           If set to a true value, all temporary working directories will be preserved on  exit  from  a  failed
           test.  The full path names of all temporary working directories will be reported on error output.

       "PRESERVE_NO_RESULT"
           If  set  to a true value, all temporary working directories will be preserved on exit from a test for
           which there is no result.  The full path names of all temporary working directories will be  reported
           on error output.

       "PRESERVE_PASS"
           If set to a true value, all temporary working directories will be preserved on exit from a successful
           test.  The full path names of all temporary working directories will be reported on error output.

       "VERBOSE"
           When  set  to  a  true value, enables verbose reporting of various internal things (path names, exact
           command line being executed, etc.).

PORTABLE TESTS

       Although the "Test::Cmd" module is intended to make it  easier  to  write  portable  tests  for  portable
       utilities  that  interact  with file systems, it is still very easy to write non-portable tests if you're
       not careful.

       The best and most comprehensive set of portability guidelines is the  standard  "Writing  portable  Perl"
       document at:

               http://www.perl.com/pub/doc/manual/html/pod/perlport.html

       To reiterate one important point from the "WpP" document:  Not all Perl programs have to be portable.  If
       the program or script you're testing is UNIX-specific, you can (and should) use the "Test::Cmd" module to
       write UNIX-specific tests.

       That  having  been  said,  here  are  some  hints  that  may  help  keep your tests portable, if that's a
       requirement.

       Use the "Test::Cmd-&"here> method for current directory path.
           The normal Perl way to fetch  the  current  working  directory  is  to  use  the  "Cwd::cwd"  method.
           Unfortunately,  the  "Cwd::cwd"  method  canonicalizes  the path name it returns, changing the native
           directory separators into the forward slashes favored by Perl and UNIX.  For most Perl scripts,  this
           makes a great deal of sense and keeps code uncluttered.

           Passing  in  a  file  name  that  has  had its directory separators altered, however, may confuse the
           command or script under test, or make it difficult to compare output from the command or script  with
           an  expected  result.   The  "Test::Cmd::here"  method  returns the absolute path name of the current
           working directory, like "Cwd::cwd", but does not manipulate the returned path in any way.

       Use "File::Spec" methods for manipulating path names.
           The "File::Spec" module provides a system-independent interface for manipulating path names.  Because
           the "Test::Cmd" class is a sub-class of the "File::Spec" class, you can use these methods directly as
           follows:

                   if (! Test::Cmd->file_name_is_absolute($prog)) {
                           my $prog = Test::Cmd->catfile(Test::Cmd->here, $prog);
                   }

           For details about the available methods and their use, see the  documentation  for  the  "File::Spec"
           module and its sub-modules, especially the "File::Spec::Unix" modules.

       Use "Config" for file-name suffixes, where possible.
           The  standard  "Config"  module provides values that reflect the file-name suffixes on the system for
           which the Perl executable was built.  This provides convenient portability  for  situations  where  a
           file name may have different extensions on different systems:

                   $foo_exe = "foo$Config{_exe}";
                   ok(-f $foo_exe);

           (Unfortunately,  there  is  no  existing  $Config  value  that  specifies  the suffix for a directly-
           executable Perl script.)

       Avoid generating executable programs or scripts.
           How to make a file or script executable varies widely from system to system, some systems using  file
           name  extensions  to indicate executability, others using a file permission bit.  The differences are
           complicated to accommodate in a portable test script.  The easiest way to deal with  this  complexity
           is to avoid it if you can.

           If your test somehow requires executing a script that you generate from the test itself, the best way
           is  to  generate  the  script in Perl and then explicitly feed it to the Perl executable on the local
           system.  To be maximally portable, use the $^X variable instead of hard-coding "perl" into the string
           you execute:

                   $line = "This is output from the generated perl script.";
                   $test->write('script', <<EOF);
                   print STDOUT "$line\\n";
                   EOF
                   $output = `$^X script`;
                   ok($output eq "$line\n");

           This completely avoids having to make the "script" file itself  executable.   (Since  you're  writing
           your test in Perl, it's safe to assume that Perl itself is executable.)

           If  you must generate a directly-executable script, then use the $Config{'startperl'} variable at the
           start of the script to generate the appropriate magic that will execute it as a Perl script:

                   use Config;
                   $line = "This is output from the generated perl script.";
                   $test->write('script', <<EOF);
                   $Config{'startperl'};
                   print STDOUT "$line\\n";
                   EOF
                   chdir($test->workdir);
                   chmod(0755, 'script');  # POSIX-SPECIFIC
                   $output = `script`;
                   ok($output eq "$line\n");

       Addtional hints on writing portable tests are welcome.

SEE ALSO

       perl(1),   Algorithm::DiffOld(3),   File::Find(3),    File::Spec(3),    Test(3),    Test::Cmd::Common(3),
       Test::Harness(3), Test::More(3), Test::Simple(3), Test::Unit(3).

       A rudimentary page for the "Test::Cmd" module is available at:

               http://www.baldmt.com/Test-Cmd/

       The  most  involved  example  of  using  the  "Test::Cmd" package to test a real-world application is the
       "cons-test" testing suite for the Cons software construction utility.  The  suite  uses  a  sub-class  of
       "Test::Cmd::Common" (which in turn is a sub-class of "Test::Cmd") 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

AUTHORS

       Steven Knight, knight@baldmt.com

COPYRIGHT

       Copyright 1999-2001 Steven Knight.  All  rights  reserved.   This  program  is  free  software;  you  can
       redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

       Thanks  to  Greg  Spencer  for  the  inspiration  to  create  this  package  and the initial draft of its
       implementation as a specific testing package for the Cons  software  construction  utility.   Information
       about Cons is available at:

               http://www.dsmit.com/cons/

       The  general idea of managing temporary working directories 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

       Thanks  to  Michael  Schwern  for  all  of  the  thoughtful  work  he's  put into Perl's standard testing
       methodology, including the "Test::Simple" and "Test::More" modules, and enhancement  and  maintenance  of
       the  "Test"  and "Test::Harness" modules.  Thanks also to Christian Lemburg for the impressively complete
       "Test::Unit" framework of modules.  Ideas from both have helped keep "Test::Cmd" flexible  enough  to  be
       useful in multiple testing frameworks.

perl v5.18.1                                       2014-01-12                                           Cmd(3pm)