ali@5:                            bookloupe test framework
ali@5:                            ========================
ali@0: 
ali@0: Running existing testcases
ali@0: --------------------------
ali@0: 
ali@5: The test harness (the program that runs a test) is called loupe-test. The
ali@5: various testcases are stored in multiple text files, typically with a .tst
ali@5: extension.
ali@0: 
ali@5: To run a testcase when all of bookloupe, loupe-test and the testcase file are
ali@0: in the current directory simply do something like:
ali@0: 
ali@5: % loupe-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@5: C:\DP> loupe-test missing-space.tst
ali@0: 
ali@0: To run all the tests in the current directory, do something like this:
ali@0: 
ali@5: % loupe-test *.tst
ali@0: 
ali@5: If bookloupe is not in the current directory or you want to run the testsuite
ali@5: against gutcheck (the program that bookloupe is based on), then you can set an
ali@5: environment variable (BOOKLOUPE) to point at it. For example, on MS-Windows
ali@5: you might do:
ali@0: 
ali@5: C:\DP> set BOOKLOUPE=C:\GUTCHECK\GUTCHECK.EXE
ali@5: C:\DP> loupe-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@5: unlikely event that you need sixteen asterisks at the start of a 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@5: Note that the header that bookloupe and gutcheck normally output is not
ali@5: included in the expected output. This avoids problems with not knowing
ali@5: beforehand the name of the file that bookloupe/gutcheck will be asked to
ali@5: look at (and saves typing!). bookloupe (and gutcheck) prints a blank line
ali@5: before each warning. These are not part of the header and so do need to
ali@5: be included.
ali@0: 
ali@5: To test that bookloupe 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@5: tag, then loupe-test will consider that no expectation exists and won't
ali@5: check the output at all.
ali@0: 
ali@0: There is no support yet for non-ASCII testcases, embedded linefeeds,
ali@5: passing command line options to bookloupe or for testcases which are
ali@0: expected to fail.