# README

INTRODUCTION

This is the cons-test package, a test suite for the Cons software
construction system.  Cons was originally written by Bob Sidebotham,
and is currently (November 1998) maintained by Rajesh Vaidheeswarran.
The home page for Cons itself can be found at:

	http://lowrent.org/cons/



CONTENTS

The contents of this release:

	ChangeLog	List of changes.

	README		What you're looking at right now.

	Tests.doc	Summary documenting what each test does
			(often in too much detail).

	cons-test.pl	Wrapper script to execute tests.

	t*a.sh		Tests.

	template.tst	Template for creating additional tests.



THE cons-test.pl SCRIPT

By default, the cons-test.pl script will test the script 'cons' in
the current directory.

An alternate 'cons' script name may be specified via the -x flag:

	$ perl cons-test.pl -x cons.NEW

	$ perl cons-test.pl -x /usr/foo/cons.experiment/cons

The 'cons' script being tested must have execute permissions set.

By default, the cons-test.pl script executes all the tests in the
local directory with the specified script, and reports a summary
of the pass/fail score:

	cons-test:  'cons' passed all 35 tests.

	cons-test:  'cons' passed 33 tests, failed 2:
			t0003a.sh
			t0026a.sh

The cons-test.pl script can be given one or more tests as arguments,
in which case it will only execute the specified tests:

	$ perl cons-test.pl t0007a.sh t0023a.sh
	cons-test.pl:  sh t0007a.sh
	PASSED
	cons-test.pl:  sh t0023a.sh
	PASSED

	cons-test.pl:  'cons' passed all 2 tests.
	$

The cons-test.pl script may also be given environment variable
assignments as arguments.  These will be evaluated in order with
the test arguments.  This allows, for example, executing the same
test(s) with different compilers in the same cons-test.pl invocation:

	$ perl cons-test.pl CC=gcc t0001a.sh CC=no_compiler t0001a.sh
	cons-test.pl:  sh t0001a.sh
	PASSED
	cons-test.pl:  sh t0001a.sh
	FAILED test #1 of cons [single-module Program]:
	no_compiler -c foo.c -o foo.o
	cons: failed to execute "no_compiler" (No such file or directory). Is this an executable on path "/bin:/usr/bin"?
	cons: *** [foo.o] Error 2
	cons: errors constructing foo.o
	FAILED test #1 of cons [single-module Program]

	cons-test.pl:  'cons' passed 1 tests, failed 1:
			t0001a.sh
	$

By default, the cons-test.pl script expects that the environment
variables $CC, $AR, and $RANLIB are set, and will generate warnings
if they are not.  A -q option may be used to suppress these warnings.



TESTS

Tests conform to requirements of the Aegis project change supervisor,
which integrates creation and execution of regression tests into
the software development process.  Information about Aegis can be
found at:

	http://www.tip.net.au/~millerp/aegis.html

Each test is a completely self-contained shell script, and should
be executed by explicitly passing it to your (Bourne or Korn) shell:

	$ sh t0001a.sh

The cryptic names are by Aegis convention only, and could have been
named to reflect the functionality being tested.  I've preserved
numbering them to give order to the tests:  Simpler, underlying
functionality is tested before more complicated features that rely
on functionality tested by prior tests.

Each test creates a temporary work directory under $TMPDIR (under
/tmp by default) and populates it with files from in-line here
documents.

Each test checks the return value from every command it executes,
expecting successful exit codes from all commands.  When it's
important, it compares actual command output against expected
output.  (Note that, with three exceptions, this actually refers
to the output of the executables generated by Cons, not the "cc"
command lines reported by Cons as part of its building the test
executables.)

By default, the tests rely on having normal C compilation, linking
and archiving tools available through the environment's PATH, and
expect that printf() is available through whatever library is linked
into a program via the default Cons build environment.  These tests
use the following environment variables for specification of
alternate paths to various utilities:

	AR	(default:  'ar')	library archiver
	CC	(default:  'cc')	C compiler
	RANLIB	(default:  'ranlib')	ranlib

As described previously, the cons-test.pl script accepts environment
variable assignments in its command-line arguments.  This may be
used, for example, to specify different C compilers for different
test invocations:

	$ perl cons-test.pl CC=gcc t0001a.sh CC=cc t0001a.sh

Each test reports one of three results:

	PASSED
		The Cons script being tested passed this test.

	FAILED test of [functionality]
		The Cons script being tested failed this test.

	NO RESULT for test of [functionality]
		The Cons script could not be tested due to
		some non-Cons problem (e.g., unable to
		create temporary directory or file).

Each test removes its temporary work directory upon completion.
For post facto debugging, the work directory can be preserved (and
its name reported) by setting environment variables:

	PRESERVE
		Don't remove the work directory.

	PRESERVE_PASS
		Don't remove the work directory if the test passes.

	PRESERVE_FAIL
		Don't remove the work directory if the test fails.

	PRESERVE_NO_RESULT
		Don't remove the work directory if there is no
		valid test result.


Changes, enhancements, portability fixes are welcome.

	Steven Knight
	knight@baldmt.com