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 When a testcase fails, loupe-test shows the output of bookloupe (or gutcheck)
34 up until the point where it deviates from the expected result and displays a
35 carat (^) to point to the exact column where the deviation occurred. Sometimes
36 it can still be difficult to work out what is happening and so loupe-test also
37 supports a -o option which will simply print bookloupe's output without comment
40 Writing your own testcases
41 --------------------------
43 Writing a new testcase is pretty painless. Most testcases follow this simple
46 ┌──────────────────────────────────────────┐
47 │**************** INPUT **************** │
48 │"Look!John, over there!" │
49 │**************** EXPECTED ****************│
51 │"Look!John, over there!" │
52 │ Line 1 column 6 - Missing space? │
53 └──────────────────────────────────────────┘
55 The sixteen asterisks in this example form what is known as the "flag". This
56 flag must come before and after all tags (eg., INPUT and EXPECTED). In the
57 unlikely event that you need sixteen asterisks at the start of a line of text,
58 then simply choose a different flag and use it throughout the file (flags
59 can be any sequence of ASCII characters except control codes and space).
61 Note that the header that bookloupe and gutcheck normally output is not
62 included in the expected output. This avoids problems with not knowing
63 beforehand the name of the file that bookloupe/gutcheck will be asked to
64 look at (and saves typing!). bookloupe (and gutcheck) prints a blank line
65 before each warning. These are not part of the header and so do need to
68 To test that bookloupe produces no output, you still need to include
69 an EXPECTED tag, just with no text following it. If there is no EXPECTED
70 tag, then loupe-test will consider that no expectation exists and won't
71 check the output at all.
76 The testcase definitions (the .tst files) are always written in UTF-8
77 which is a superset of ASCII. Since gutcheck does not understand UTF-8
78 this causes a problem when it is desired to include characters that
79 are not in ASCII in a testcase. To solve this problem it is possible
80 to specify an encoding to use for the test. It is very important to
81 undertand that this specifies the encoding that loupe-test will use to
82 talk to bookloupe/gutcheck and _not_ the encoding of the .tst file
83 (which remains UTF-8). gutcheck understands Latin-1 (at least to a
84 limited extent), the canonical name for which is ISO-8859-1:
86 ┌─────────────────────────────────────────────────────────────────┐
87 │**************** ENCODING **************** │
89 │**************** INPUT **************** │
90 │"Hello," he said, "I wanted to bave a tête-à-tête with you." │
91 │**************** EXPECTED **************** │
93 │"Hello," he said, "I wanted to bave a tête-à-tête with you." │
94 │ Line 1 column 31 - Query word bave - not reporting duplicates│
95 └─────────────────────────────────────────────────────────────────┘
100 One of the tests that bookloupe/gutcheck need to do is check that all
101 lines are ended with CR NL (as required by PG) rather than the UNIX
102 standard NL. loupe-test deliberately ignores the line endings in testcase
103 definition files and always uses CR NL. Thus there is needed a means
104 to embed a linefeed (aka newline) character into the input to be sent
105 to bookloupe/gutcheck to test that it correctly identified the problem.
106 loupe-test recognises the unicode symbol for linefeed (U+240A): ␊ which
107 can be used for this purpose instead of a normal newline.
109 Passing command line options
110 ----------------------------
112 Some of bookloupe's functionality is only available using command line
113 options. loupe-test provides a means of specifying these with the
116 ┌──────────────────────────────────────────┐
117 │**************** OPTIONS **************** │
120 │**************** INPUT **************** │
121 │“He went <i>thataway!</i>” │
122 │**************** EXPECTED ****************│
123 └──────────────────────────────────────────┘
128 Under certain circumstances, bookloupe reads other input files than just
129 the ebook. These can be specified in the testcase definition file by
130 adding the name of the file to the INPUT tag:
132 ┌───────────────────────────────────────────────────────────────┐
133 │**************** OPTIONS **************** │
135 │**************** INPUT(gutcheck.typ) **************** │
137 │**************** INPUT **************** │
138 │I am the very model of a modern Major-General, │
139 │I've information vegetable, animal, and mineral, │
140 │I know the kings of England, arid I quote the fights historical│
141 │From Marathon to Waterloo, in order categorical; │
142 │I'm very well acquainted, too, with matters mathematical, │
143 │I understand equations, both the simple and quadratical, │
144 │About binomial theorem I'm teeming with a lot o' news-- │
145 │With many cheerful facts about the square of the hypotenuse. │
146 │**************** EXPECTED **************** │
148 │I know the kings of England, arid I quote the fights historical│
149 │ Line 3 column 29 - Query possible scanno arid │
150 └───────────────────────────────────────────────────────────────┘
155 Bookloupe normally follows a standard pattern when printing warnings which
156 loupe-test knows how to interpret. Occasionally this is not suitable and
157 the testcase needs to specify exactly what should be printed. This can
158 be done by adding a literal stdout to the EXPECTED tag:
160 ┌───────────────────────────────────────────────────────────────┐
161 │**************** OPTIONS **************** │
163 │**************** EXPECTED(stdout) **************** │
164 │# Trivial configuration │
168 └───────────────────────────────────────────────────────────────┘
173 Most of the time, the input can be tweaked so that all warnings bookloupe
174 reports represent real errors in the text. Sometimes, however, this either
175 cannot be done and still test what we need to. In these cases we need a
176 means to describe these false-positives (warnings that do not describe
177 a real error). This is important so that a later version of bookloupe can
178 be improved to not issue the false-positive warning and still pass the
179 test. In order to do this, we need to describe the warnings in a more
180 structures manner, like this:
182 ┌───────────────────────────────────────────────────────────────┐
183 │**************** OPTIONS **************** │
185 │**************** INPUT **************** │
186 │'In a moment,' Peter replied,' I'm just coming.' │
188 │'Underneath the girls' scarves. │
190 │**************** WARNINGS **************** │
193 │ <at line="1" column="30"/> │
194 │ <text>Wrongspaced singlequotes?</text> │
198 │ <text>Mismatched singlequotes?</text> │
199 │ </false-positive> │
201 │ <at line="3" column="1"/> │
203 │ <text>Mismatched singlequotes?</text> │
204 │ </false-negative> │
206 └───────────────────────────────────────────────────────────────┘
208 Here, we use the "WARNINGS" tag instead of "EXPECTED" to denote that we
209 wish to use structured warnings and the list of warnings is enclosed in
210 an <expected> ... </expected> node.
212 Each warning, or potential warnings is then described using either an
213 "error" node (for warnings that represent real errors in the text), a
214 "false-positive" node (for warnings that do not represent real errors),
215 or a "false-negative" node (for warnings that should be issued, but that
216 are not yet detected by bookloupe).
218 Within each warning node, there are then one or more "at" nodes which
219 list the acceptable locations for the warning to be reported at (the
220 first listed should be the preferred location) and exactly one "text"
221 node which must match the text of the warning issued.
223 A testcase will pass if all the warnings marked as errors were issued and
224 if no warnings were issued that are not listed in one form or another.
225 If the testcase passes with an expected failure (ie., issues a warning
226 for a false positive or does not issue a warning for a false negative),
227 then the test is counted as passed, but a note will be printed describing
230 sample: PASS (with 1 of 1 false positives and 1 of 1 false negatives)