-$Id: README,v 1.4 2002-11-20 22:50:45 mike Exp $
-cql-java's regression-testing framework
+If you just don't want to think about it
+----------------------------------------
+
+Just use "make" to run regression tests.
+
+
+CQL-Java's regression-testing framework
---------------------------------------
"queries.raw" is the file of test queries as provided by Rob.
"runtests" compares the output of a nominated CQL compiler with
existing XCQL files. Most often, you'll use this to compare the
-results of your own build of cql-java with those of my build. I'll
+results of your own build of CQL-Java with those of my build. I'll
use it to test new versions, and people who've written other compilers
-can use it to test their code.
+can use it to test their code. (The code of "runtests" and
+"mkanswers" is worryingly similar: they should probably be the same
+program invoked with different command-line arguments.)
"Makefile" controls the building of all this. You'll need to edit it
if you want to use different compilers and suchlike from what's
first, then the next "make" will rebuild the reference results.
So, for example, if you think Rob Sanderson's parser, CQLParser.py, is
-reliable, and you want to test my parser, cql-java's CQLParser class,
+reliable, and you want to test my parser, CQL-Java's CQLParser class,
against its results, do this:
make refclean
./mktests queries.raw
./mkanswers CQLParser.py
- ./runtests CQLParser ./xmlpp.pl
+ ./runtests ../../bin/CQLParser ./xmlpp.pl
The second argument to ./runtests is the name of a program to use to
normalise XML, so that the trusted output and the output being tested
pretty-printer from DecisionSoft, found at
http://software.decisionsoft.com/tools.html
+"showtest" can be used to run a single test showing more details of
+what goes wrong, if anything. You don't need it as part of the
+regression test, but it's useful when debugging.
+
+Finally, "runcanon" checks that each of the queries when compiled and
+decompiled back to CQL (i.e. canonicalised) remains identical when
+recompiled and redecompiled.
+
Appendix: queries that should fail
----------------------------------