/ 
cons-plus-tests-2.0.1
/ Test::Cmd::Cons

NAME

Test::Cmd::Cons - module for testing the Cons software construction utility

SYNOPSIS

  use Test::Cmd::Cons;

  $test = Test::Cmd::Cons->new(string => 'functionality being tested');

  $test->cons;

  $test->cons_env;
  $test->cons_env('CC => "gcc", AR => 'ar', RANLIB => 'ranlib'");

  $test->cons_env_val('VARIABLE');

  $test->run(chdir => 'subdir', fail => '$? != 0',
		flags => '-x', targets => '.',
		stdout => <<_EOF_, stderr => <<_EOF_);
  standard output
  _EOF_
  error output
  _EOF_

  $test->up_to_date(chdir => 'subdir', flags => '-x', targets => '.');

  $test->execute(prog => 'foo.pl', interpreter => $^X,
		args => '-f arg1 arg2', fail => '$? != 0',
		expect => <<_EOF_);
  expected 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->sleep($seconds);

  $test->touch('file', ...);

  $test->unlink('file', ...);

  use Test::Cmd::Cons qw($_exe $_o $_a);

DESCRIPTION

The Test::Cmd::Cons module provides a simple, high-level interface for writing tests of the Cons software construction utility.

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::Cons module provides three importable variables: $_exe, $_o, and $_a. These are respectively, the values normally available from $Config{_exe} (executable file suffix), $Config{_o} (object file suffix) and $Config{_a} (library suffix). These $Config values, however, are not available prior to Perl 5.005, so the Test::Cmd::Cons module figures out proper values via other means, if necessary.

METHODS

new

Creates a new Cons 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 (typically the Test::Cmd class). In the normal case, this need only be the string describing the functionality being tested:

$test = Test::Cmd::Cons->new(string => 'cool new feature');

Creates a temporary working directory for the test environment and changes directory to it.

The Cons script under test will be passed to perl, with the directory from which it was invoked appended with -I, allowing Cons to use modules installed in the current directory.

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.

cons

Returns the Cons program to be executed for the specified test environment, optionally setting it to the specified argument.

cons_env

Returns the string representation of the Cons environment for the specified test environment, optionally setting it to the specified argument. Typically used to interpolate the Cons environment into a Construct or Conscript file:

$test->write('Construct', <<_EOF_);
\$Env = new cons ( ${\$test->cons_env} );
_EOF_
cons_env_val

Fetches a specified value from the Cons environment for the specified test environment. Typically used to fetch the current compiler, linker, flags, or some other variable:

$CC = $test->cons_env_val('CC');
run

Runs a test on Cons, checking that the test succeeded. Arguments are keyword-value pairs that affect the manner in which Cons 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. Cons exits unsuccesfully.  A
      not-uncommon alternative is:

	  $test->run(fail => '$? == 0');	# expect failure

      when testing how Cons 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.  Each expected line
      is a regular expression to match against the corresponding line
      in the file:

	  $test->run(stdout => <<_EOF_);
	  Multiple (line|lines)?
	  containing \Q$^X\E regular expressions
	  _EOF_

  --  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.  Each expected line is a regular
      expression to match against the corresponding line in the file:

	  $test->run(stderr => <<_EOF_);
	  Multiple (line|lines)?
	  containing \Q$^X\E regular expressions
	  _EOF_
up_to_date

Runs Cons, specifically checking to make sure that the specified targets are already up-to-date, and nothing was rebuilt. Takes the following keyword-value argument pairs:

chdir => 'subdir'
flags => 'Cons flags',
targets => 'targets to build'

The test fails if:

Cons exits with an error (non-zero) status
Cons reports anything being rebuilt
Cons generates any error output
execute

Executes a program or script other than the Cons under test (typically an executable built by the Cons invocation we're testing).

args => 'command line arguments'
fail => 'failure condition'	# default is '$? != 0'
interpreter => 'prog_interpreter'
prog => 'progam_to_execute'
stderr => 'expected error output'
stdout => 'expected standard output'

The execution fails if:

  --  The specified failure condition is met.  The default failure
      condition is '$? != 0', i.e. the program exits unsuccesfully.

  --  Actual standard output does not match expected standard output
      (if any).  The expected output is an array of lines or a scalar
      which will be split on newlines.  Each expected line is a regular
      expression to match against the corresponding line in the file:

	  $test->run(stdout => <<_EOF_);
	  Multiple (line|lines)?
	  containing \Q$^X\E regular expressions
	  _EOF_

  --  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.  Each expected line is a regular
      expression to match against the corresponding line in the file:

	  $test->run(stderr => <<_EOF_);
	  Multiple (line|lines)?
	  containing \Q$^X\E 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. Each expected line is a regular expression to match against the corresponding line in the file:

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

The expe

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.

sleep

Sleeps at least the specified number of seconds. 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.

Removes the specified files. Exits NO RESULT if any file could not be removed for any reason.

ENVIRONMENT

The Test::Cmd::Cons module uses the following environment variables:

CONS

The Cons script under test. This may be an absolute or relative path. The script will be fed to perl and need not have execute permissions set.

CONSENV

The Cons environment to use for tests. This should be a string that will be interpreted as a hash specifying the values for the local compiler, linker, flags, etc., to be used for the tests:

$ export CONSENV="CC => 'gcc', AR => 'ar', LINK => 'ld'"
$ perl cons-test.pl

The Test::Cmd::Cons 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).

AUTHOR

Steven Knight, knight@baldmt.com

ACKNOWLEDGEMENTS

Thanks to Greg Spencer for the inspiration to create this package and to rewrite all of the cons-test scripts in Perl.

The general idea of testing Cons 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