test/regression/README

   1 $Id: README,v 1.3 2002-11-20 01:15:15 mike Exp $
   2
   3 cql-java's regression-testing framework
   4 ---------------------------------------
   5
   6 "queries.raw" is the file of test queries as provided by Rob.
   7 "mktests" parses the raw file into sections and individual queries
   8 "sections" is the top-level directory created by that program.
   9   "01", "02" etc. represent the sections within the raw file
  10     "01/name", "02/name", etc. contain the names of the sections.
  11     "01/01.cql", "01/02.cql" etc. are the CQL queries themselves.
  12 "mkanswers" uses a trusted CQL compiler to generate corresponding XCQL.
  13     "01/01.xcql", "01/02.xcql" etc. are the compiled XCQL queries.
  14
  15 All of the files described to this point are included in the
  16 distribution, with the "trusted" outpout produced by my own compiler,
  17 and used to for regression testing of new versions.  But you're
  18 welcome to "rm -r sections" and rebuild it to contain the trusted
  19 compiler output of your choice.
  20
  21 "runtests" compares the output of a CQL compiler with existing XCQL
  22 files.  In general, use this to compare the results of your own build
  23 of cql-java with those of my build.  (I'll use it to test new
  24 versions, and people who've written other compilers can use it to test
  25 their code.)
  26
  27 "Makefile" controls the building of all this.  You'll need to edit it
  28 if you want to use different compilers and suchlike from what's
  29 written into it, so it may be easier to run the tests by hand -- but
  30 it's a useful reference for the kinds of commands you might need,
  31 anyway.  In general, "make" will run the regression tests, and "make
  32 reference" will rebuild the reference results should you wish to do
  33 that.
  34
  35 So, for example, if you think Rob Sanderson's parser, CQLParser.py, is
  36 reliable, and you want to test my parser, cql-java's CQLParser class,
  37 against its results, do this:
  38
  39         rm -rf sections
  40         ./mktests queries.raw
  41         ./mkanswers CQLParser.py
  42         ./runtests CQLParser ./xmlpp.pl
  43
  44 The second argument to ./runtests is the name of a program to use to
  45 normalise XML, so that the trusted output and the output being tested
  46 can be compared for equivalence rather than just for being
  47 byte-identical.  (If you want to test for byte-identical XCQL, then
  48 use "cat" as the second argument.)  xmlpp.pl is a fine XML
  49 pretty-printer from DecisionSoft, found at
  50         http://software.decisionsoft.com/tools.html
  51