test/regression/README

   1 $Id: README,v 1.8 2007-06-29 13:06:07 mike Exp $
   2
   3 If you just don't want to think about it
   4 ----------------------------------------
   5
   6 Just use "make" to run regression tests.
   7
   8
   9 CQL-Java's regression-testing framework
  10 ---------------------------------------
  11
  12 "queries.raw" is the file of test queries as provided by Rob.
  13 "mktests" parses the raw file into sections and individual queries
  14 "sections" is the top-level directory created by that program.
  15   "01", "02" etc. represent the sections within the raw file
  16     "01/name", "02/name", etc. contain the names of the sections.
  17     "01/01.cql", "01/02.cql" etc. are the CQL queries themselves.
  18 "mkanswers" uses a trusted CQL compiler to generate corresponding XCQL.
  19     "01/01.xcql", "01/02.xcql" etc. are the compiled XCQL queries.
  20
  21 Apart from the CQL files, all of the files described to this point are
  22 included in the distribution, with the "trusted" XCQL output produced
  23 by my own compiler, and used for regression testing of new versions.
  24 The CQL files are re-created from "queries.raw" as required.  But
  25 you're welcome to "make refclean" and rebuild it with mkanswers, to
  26 contain the trusted compiler output of your choice.
  27
  28 "runtests" compares the output of a nominated CQL compiler with
  29 existing XCQL files.  Most often, you'll use this to compare the
  30 results of your own build of CQL-Java with those of my build.  I'll
  31 use it to test new versions, and people who've written other compilers
  32 can use it to test their code.  (The code of "runtests" and
  33 "mkanswers" is worryingly similar: they should probably be the same
  34 program invoked with different command-line arguments.)
  35
  36 "Makefile" controls the building of all this.  You'll need to edit it
  37 if you want to use different compilers and suchlike from what's
  38 written into it, so it may be easier to run the tests by hand -- but
  39 it's a useful reference for the kinds of commands you might need,
  40 anyway.  In general, "make" will run the regression tests, creating
  41 whatever CQL and/or XCQL files it needs; if you do "make refclean"
  42 first, then the next "make" will rebuild the reference results.
  43
  44 So, for example, if you think Rob Sanderson's parser, CQLParser.py, is
  45 reliable, and you want to test my parser, CQL-Java's CQLParser class,
  46 against its results, do this:
  47
  48         make refclean
  49         ./mktests queries.raw
  50         ./mkanswers CQLParser.py
  51         ./runtests ../../bin/CQLParser ./xmlpp.pl
  52
  53 The second argument to ./runtests is the name of a program to use to
  54 normalise XML, so that the trusted output and the output being tested
  55 can be compared for equivalence rather than just for being
  56 byte-identical.  (If you want to test for byte-identical XCQL, then
  57 use "cat" as the second argument.)  xmlpp.pl is a fine XML
  58 pretty-printer from DecisionSoft, found at
  59         http://software.decisionsoft.com/tools.html
  60
  61 "showtest" can be used to run a single test showing more details of
  62 what goes wrong, if anything.  You don't need it as part of the
  63 regression test, but it's useful when debugging.
  64
  65 Finally, "runcanon" checks that each of the queries when compiled and
  66 decompiled back to CQL (i.e. canonicalised) remains identical when
  67 recompiled and redecompiled.
  68
  69
  70 Appendix: queries that should fail
  71 ----------------------------------
  72
  73 The following queries are included in Rob's master list, in a final
  74 section called "Invalid searches [should error]".  They are all
  75 expected to fail in various ways.  I've taken them out of
  76 "queries.raw" because it's uninteresting, not to mention rather
  77 disturbing, to watch compilers fail.  More important, I think, to
  78 demonstrate correct behaviour for the known-to-work queries.
  79
  80 >
  81 ===
  82 cat or
  83 index any
  84 index any/wrong term
  85 a prox/wrong b
  86 ()
  87 (a
  88 index any fish)
  89 (cat any dog or ())
  90 title = ("illegal parentheses")
  91 "quoted" any "illegal quotes"
  92 > illegal="urn:missingQuery"
  93 "fish" and > illegal="urn:invalidPrefixLocation" "chips"