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