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 CWTest::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 CWTest::Cmd::Common class is a subclass of CWTest::Cmd. In essence, CWTest::Cmd::Common is a wrapper that treats common CWTest::Cmd error conditions as exceptions that terminate the test. You can use CWTest::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, CWTest::Cmd::Common serves as a useful example of how to define your own CWTest::Cmd subclass.

The CWTest::Cmd::Common module provides the following importable variables: The executable file suffix. This value is normally available as CW$Config{_exe} in Perl version 5.005 and later. The CWTest::Cmd::Common module figures it out via other means in earlier versions. The object file suffix. This value is normally available from CW$Config{_o} in Perl version 5.005 and later. The CWTest::Cmd::Common module figures it out via other means in earlier versions. The library file suffix. This value is normally available from as CW$Config{_a} in Perl version 5.005 and later. The CWTest::Cmd::Common module figures it out via other means in earlier versions. The shared library file suffix. This value is normally available as CW$Config{_so} in Perl version 5.005 and later. The CWTest::Cmd::Common module figures it out via other means in earlier versions. A Boolean value that reflects whether the current platform is a Win32 system.

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 CWTest::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');

    $test = Test::Cmd::Common->new(prog => 'my_program',
                                   string => 'cool new feature',
                                   match_sub => \&Test::Cmd::diff_regex);

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

    chdir => 'subdir'
    fail => 'failure condition' # default is '$? != 0'
    flags => 'Cons flags'
    stderr => 'expected error output'
    stdout => 'expected standard output'
    targets => 'targets to build'

  --  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);

    $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_

    $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_

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

    $test->file_matches('file', <<_EOF_);
    The (1st|first) line\.
    The (2nd|second) line\.
    _EOF_

The CWTest::Cmd::Common module also uses the CWPRESERVE, CWPRESERVE_FAIL, CWPRESERVE_NO_RESULT, and CWPRESERVE_PASS environment variables from the CWTest::Cmd module. See the CWTest::Cmd documentation for details.

perl(1), Test::Cmd(3).

The most involved example of using the CWTest::Cmd::Common module to test a real-world application is the CWcons-test testing suite for the Cons software construction utility. The suite sub-classes CWTest::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 CWpass, CWfail and CWno_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