#
# @(#)README	1.3	97/04/22
#

This file contains the documentation for the recent changes made
to the test directory structure. It tells one how to create
makefiles conforming to this structure and how to write and add
tests to the area.

The organisation for the test area is now very similar to the rest
of the build area. Under the security directory there is one directory
for each of the major features that are being added to the security
architecture. Thus there are directories for permission, policy, attacks,
signed applets, etc. Each feature-directory has a makefile which mentions
only certain key macros and depends on a standard set of utility makefiles
to do the rest of the functions of compiling, running and reporting test
execution.

Writing Makefiles:
------------------
To create a makefile, the following macros are key:

TOPDIR:	This macro represents the path from the current directory all the way
	up to the root of this workspace i.e the directory having the src and
	build directories.

TESTS: 	This macro lists the java files which represent the entry point for
        each of the tests to be run.
 
SRCS: 	This macro lists (in addition to TESTS) those other java files which need
	to be compiled.

(In your makefiles for each test subdirectory be sure to define these macros.)


In addition to defining these macros, one will need to include the following
makefiles from the directory ./makefiles.

Defs.gmk:	This makefile contains some standard macros that are needed
		for finding the correct sources and classes to use.

Execute.gmk:	This makefile contains the standard targets to use for
		compiling, running, diffing files and reporting results.

(In your makefiles, be sure to include these files by adding the following
statements:

include ../makefiles/Defs.gmk
include ../makefiles/Execute.gmk

Note that the '..' may vary depending on the depth of the test subdir.)

Check out the template makefile (makefiletemplate.gmk) in the ./templates directory.

Writing Tests:
--------------

Two files are necessary to write tests:
	Status.java
	Test.java

These two files have been put into the ./lib directory. The Class Status
is used to return a status code back from the test. The following are
the return code:

	Status.passed()    : if the test passed
	Status.failed()    : if the test failed
	Status.checkFile() : if the test involves a diff with a
			     <testname>.result file.


The Test.java file defines an interface which each test should implement.
The only method in the Test interface is the run method with the following
syntax:

	public Status run(String args[], PrintStream log, PrintStream.ref)

All the important functionality of the test should be in this method. The
main() method merely calls this method to run the test and gets a return
code from the test. Tests should be selfchecking as far as possible and
should only depend on output if it is absolutely necessary to check the
output of a given operation.

The output of a test is automatically gathered into <testname>.output
and compared with <testname>.result file.

Please refer to the sample test file for details on writing the test.

Check out the template test file (testtemplate.gmk) in the ./templates directory.

(This document is a first cut. Please send all feedback to vijay@thought.)

Vijay
