1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/gc-test.txt	Wed Jan 25 19:33:43 2012 +0000
     1.3 @@ -0,0 +1,64 @@
     1.4 +                            gutcheck test framework
     1.5 +                            =======================
     1.6 +
     1.7 +Running existing testcases
     1.8 +--------------------------
     1.9 +
    1.10 +The test harness (the program that runs a test) is called gc-test. The various
    1.11 +testcases are stored in multiple text files, typically with a .tst extension.
    1.12 +
    1.13 +To run a testcase when all of gutcheck, gc-test and the testcase file are
    1.14 +in the current directory simply do something like:
    1.15 +
    1.16 +% gc-test missing-space.tst
    1.17 +
    1.18 +from a command prompt. Under MS-Windows, this is called a command window and
    1.19 +the prompt will normally look slightly different, eg.,
    1.20 +
    1.21 +C:\DP> gc-test missing-space.tst
    1.22 +
    1.23 +To run all the tests in the current directory, do something like this:
    1.24 +
    1.25 +% gc-test *.tst
    1.26 +
    1.27 +If gutcheck is not in the current directory, then you can set an environment
    1.28 +variable (GUTCHECK) to point at it. For example, on MS-Windows you might do:
    1.29 +
    1.30 +C:\DP> set GUTCHECK=C:\GUTCHECK\GUTCHECK.EXE
    1.31 +C:\DP> gc-test *.tst
    1.32 +
    1.33 +Writing your own testcases
    1.34 +--------------------------
    1.35 +
    1.36 +Writing a new testcase is pretty painless. Most testcases follow this simple
    1.37 +pattern:
    1.38 +
    1.39 +		┌──────────────────────────────────────────┐
    1.40 +		│**************** INPUT ****************   │
    1.41 +		│"Look!John, over there!"                  │
    1.42 +		│**************** EXPECTED ****************│
    1.43 +		│                                          │
    1.44 +		│"Look!John, over there!"                  │
    1.45 +		│    Line 1 column 6 - Missing space?      │
    1.46 +		└──────────────────────────────────────────┘
    1.47 +
    1.48 +The sixteen asterisks in this example form what is known as the "flag". This
    1.49 +flag must come before and after all tags (eg., INPUT and EXPECTED). In the
    1.50 +unlikely event that you need sixteen asterisks at the start of line of text,
    1.51 +then simply choose a different flag and use it throughout the file (flags
    1.52 +can be any sequence of ASCII characters except control codes and space).
    1.53 +
    1.54 +Note that the header that gutcheck normally outputs is not included in the
    1.55 +expected output. This avoids problems with not knowing beforehand the name
    1.56 +of the file that gutcheck will be asked to look at (and saves typing!).
    1.57 +gutcheck prints a blank line before each warning. These are not part of the
    1.58 +header and so do need to be included.
    1.59 +
    1.60 +To test that gutcheck produces no output, you still need to include
    1.61 +an EXPECTED tag, just with no text following it. If there is no EXPECTED
    1.62 +tag, then gc-test will consider that no expectation exists and won't check
    1.63 +the output at all.
    1.64 +
    1.65 +There is no support yet for non-ASCII testcases, embedded linefeeds,
    1.66 +passing command line options to gutcheck or for testcases which are
    1.67 +expected to fail.