ali@0:                             gutcheck test framework
ali@0:                             =======================
ali@0: 
ali@0: Running existing testcases
ali@0: --------------------------
ali@0: 
ali@0: The test harness (the program that runs a test) is called gc-test. The various
ali@0: testcases are stored in multiple text files, typically with a .tst extension.
ali@0: 
ali@0: To run a testcase when all of gutcheck, gc-test and the testcase file are
ali@0: in the current directory simply do something like:
ali@0: 
ali@0: % gc-test missing-space.tst
ali@0: 
ali@0: from a command prompt. Under MS-Windows, this is called a command window and
ali@0: the prompt will normally look slightly different, eg.,
ali@0: 
ali@0: C:\DP> gc-test missing-space.tst
ali@0: 
ali@0: To run all the tests in the current directory, do something like this:
ali@0: 
ali@0: % gc-test *.tst
ali@0: 
ali@0: If gutcheck is not in the current directory, then you can set an environment
ali@0: variable (GUTCHECK) to point at it. For example, on MS-Windows you might do:
ali@0: 
ali@0: C:\DP> set GUTCHECK=C:\GUTCHECK\GUTCHECK.EXE
ali@0: C:\DP> gc-test *.tst
ali@0: 
ali@0: Writing your own testcases
ali@0: --------------------------
ali@0: 
ali@0: Writing a new testcase is pretty painless. Most testcases follow this simple
ali@0: pattern:
ali@0: 
ali@0: 		┌──────────────────────────────────────────┐
ali@0: 		│**************** INPUT ****************   │
ali@0: 		│"Look!John, over there!"                  │
ali@0: 		│**************** EXPECTED ****************│
ali@0: 		│                                          │
ali@0: 		│"Look!John, over there!"                  │
ali@0: 		│    Line 1 column 6 - Missing space?      │
ali@0: 		└──────────────────────────────────────────┘
ali@0: 
ali@0: The sixteen asterisks in this example form what is known as the "flag". This
ali@0: flag must come before and after all tags (eg., INPUT and EXPECTED). In the
ali@0: unlikely event that you need sixteen asterisks at the start of line of text,
ali@0: then simply choose a different flag and use it throughout the file (flags
ali@0: can be any sequence of ASCII characters except control codes and space).
ali@0: 
ali@0: Note that the header that gutcheck normally outputs is not included in the
ali@0: expected output. This avoids problems with not knowing beforehand the name
ali@0: of the file that gutcheck will be asked to look at (and saves typing!).
ali@0: gutcheck prints a blank line before each warning. These are not part of the
ali@0: header and so do need to be included.
ali@0: 
ali@0: To test that gutcheck produces no output, you still need to include
ali@0: an EXPECTED tag, just with no text following it. If there is no EXPECTED
ali@0: tag, then gc-test will consider that no expectation exists and won't check
ali@0: the output at all.
ali@0: 
ali@0: There is no support yet for non-ASCII testcases, embedded linefeeds,
ali@0: passing command line options to gutcheck or for testcases which are
ali@0: expected to fail.