-----------------
Running the tests
-----------------

Run the functional test suite by calling functionalTesting/runTests.sh. 
This searches in the directories beneath the current directory for files
called policy.test, cd's to directories where it finds such files, and then
calls functionalTesting/tester.pl.

When run, tester.pl looks for a file called "policy.test" in the current
directory, which contains lines of the form
name<TAB>progname<TAB>options<TAB>postoptions
and a file called "base" which contains items of the form

/Xpath/string/for/testing
<expected>
  <xml>
    <output />
  </xml>
</expected>
%

It will take the first line of each test block, and run the command
progname options xpathstring postoptions
for each test block, comparing the output with the expected output, then
save any discrepancies in a file called failures.name.
Typically progname is evaluator/eval or examples/xgrep, options is either
empty or -f, and postoptions is either empty or the name of an XML file.

If tester.pl is run with the -f option, then tests with #FAIL in the first
line will be run (usually they are ignored). If any pass, the user is given
the option to remove the #FAIL.

-----------------
Making more tests
-----------------

To write more tests, create a subdirectory of functionalTesting containing
files called policy.test and base, with formats as follows:

policy.test:
purpose_of_directory
# Comments on a line by themselves, starting with a hash sign.
policy_name1<TAB>progname<TAB>options<TAB>postoptions
policy_name2<TAB>progname<TAB>options<TAB>postoptions

[Note that there is no need to redirect standard error in postoptions: this is
done by tester.pl]
You'll usually only need one policy line, but see exprTesting/common for an
example of where two are needed. The tests in base are run once for each
policy. The expected results can't vary, but the program run and the options
(for instance, the XML file or the fallback exception policy) can.

base:
/Xpath/string/for/testing
expected output line 1
expected output line 2  # Comments are Perl-style, from # to EOL
expected output line 3
expected output line 4
...
%
/Second/xpath/string/for/testing #FAIL - see bug no. xyxyxy
expected output line 1           #This test will fail, so isn't usually run.
...
%
etc.

There are two utilities to make this slightly easier:
functionalTesting/makepol and functionalTesting/exprTesting/createBase.pl.
Call makepol as follows: makepol purpose policy1 policy2 ...
This will create a policy.test file in the current directory, with purpose as
its first line and policy1, policy2 etc as names of the different policy
lines. createBase.pl is old and somewhat deprecated: it looks for a file
called test.xpt in the current directory, runs eval on every line of it, and
then prints output suitable for use as a base file on the standard output. The
problems with this approach are that you will be tempted to accept what eval
gives you instead of what should be right, and you will end up with
synchronisation problems if you don't throw away test.xpt immediately. A
better approach is to write the tests in base, then run "perl -i -ne 'print
"$_%\n"' base", and then fill in the answers yourself. Reading it easily could
probably be done with some sort of custom folding mode in your editor.
