1 bookloupe test framework
2 ========================
4 Running existing testcases
5 --------------------------
7 The test harness (the program that runs a test) is called loupe-test. The
8 various testcases are stored in multiple text files, typically with a .tst
11 To run a testcase when all of bookloupe, loupe-test and the testcase file are
12 in the current directory simply do something like:
14 % loupe-test missing-space.tst
16 from a command prompt. Under MS-Windows, this is called a command window and
17 the prompt will normally look slightly different, eg.,
19 C:\DP> loupe-test missing-space.tst
21 To run all the tests in the current directory, do something like this:
25 If bookloupe is not in the current directory or you want to run the testsuite
26 against gutcheck (the program that bookloupe is based on), then you can set an
27 environment variable (BOOKLOUPE) to point at it. For example, on MS-Windows
30 C:\DP> set BOOKLOUPE=C:\GUTCHECK\GUTCHECK.EXE
31 C:\DP> loupe-test *.tst
33 Writing your own testcases
34 --------------------------
36 Writing a new testcase is pretty painless. Most testcases follow this simple
39 ┌──────────────────────────────────────────┐
40 │**************** INPUT **************** │
41 │"Look!John, over there!" │
42 │**************** EXPECTED ****************│
44 │"Look!John, over there!" │
45 │ Line 1 column 6 - Missing space? │
46 └──────────────────────────────────────────┘
48 The sixteen asterisks in this example form what is known as the "flag". This
49 flag must come before and after all tags (eg., INPUT and EXPECTED). In the
50 unlikely event that you need sixteen asterisks at the start of a line of text,
51 then simply choose a different flag and use it throughout the file (flags
52 can be any sequence of ASCII characters except control codes and space).
54 Note that the header that bookloupe and gutcheck normally output is not
55 included in the expected output. This avoids problems with not knowing
56 beforehand the name of the file that bookloupe/gutcheck will be asked to
57 look at (and saves typing!). bookloupe (and gutcheck) prints a blank line
58 before each warning. These are not part of the header and so do need to
61 To test that bookloupe produces no output, you still need to include
62 an EXPECTED tag, just with no text following it. If there is no EXPECTED
63 tag, then loupe-test will consider that no expectation exists and won't
64 check the output at all.
66 There is no support yet for non-ASCII testcases, embedded linefeeds,
67 passing command line options to bookloupe or for testcases which are