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@10: Non-ASCII testcases ali@10: ------------------- ali@10: ali@10: The testcase definitions (the .tst files) are always written in UTF-8 ali@10: which is a superset of ASCII. Since gutcheck does not understand UTF-8 ali@10: this causes a problem when it is desired to include characters that ali@10: are not in ASCII in a testcase. To solve this problem it is possible ali@10: to specify an encoding to use for the test. It is very important to ali@10: undertand that this specifies the encoding that loupe-test will use to ali@10: talk to bookloupe/gutcheck and _not_ the encoding of the .tst file ali@10: (which remains UTF-8). gutcheck understands Latin-1 (at least to a ali@10: limited extent), the canonical name for which is ISO-8859-1: ali@10: ali@10: ┌─────────────────────────────────────────────────────────────────┐ ali@10: │**************** ENCODING **************** │ ali@10: │ISO-8859-1 │ ali@10: │**************** INPUT **************** │ ali@10: │"Hello," he said, "I wanted to bave a tête-à-tête with you." │ ali@10: │**************** EXPECTED **************** │ ali@10: │ │ ali@10: │"Hello," he said, "I wanted to bave a tête-à-tête with you." │ ali@10: │ Line 1 column 31 - Query word bave - not reporting duplicates│ ali@10: └─────────────────────────────────────────────────────────────────┘ ali@10: ali@10: Embedded linefeeds ali@10: ------------------ ali@10: ali@10: One of the tests that bookloupe/gutcheck need to do is check that all ali@10: lines are ended with CR NL (as required by PG) rather than the UNIX ali@10: standard NL. loupe-test deliberately ignores the line endings in testcase ali@10: definition files and always uses CR NL. Thus there is needed a means ali@10: to embed a linefeed (aka newline) character into the input to be sent ali@10: to bookloupe/gutcheck to test that it correctly identified the problem. ali@10: loupe-test recognises the unicode symbol for linefeed (U+240A): ␊ which ali@10: can be used for this purpose instead of a normal newline. ali@10: ali@10: Passing command line options ali@10: ---------------------------- ali@10: ali@10: Some of bookloupe's functionality is only available using command line ali@10: options. loupe-test provides a means of specifying these with the ali@10: OPTIONS tag: ali@10: ali@10: ┌──────────────────────────────────────────┐ ali@10: │**************** OPTIONS **************** │ ali@10: │-m │ ali@10: │-d │ ali@10: │**************** INPUT **************** │ ali@10: │“He went thataway!” │ ali@10: │**************** EXPECTED ****************│ ali@10: └──────────────────────────────────────────┘ ali@10: ali@10: Extra input files ali@10: ----------------- ali@10: ali@10: Under certain circumstances, bookloupe reads other input files than just ali@10: the ebook. These can be specified in the testcase definition file by ali@10: adding the name of the file to the INPUT tag: ali@10: ali@10: ┌───────────────────────────────────────────────────────────────┐ ali@10: │**************** OPTIONS **************** │ ali@10: │-u │ ali@10: │**************** INPUT(gutcheck.typ) **************** │ ali@10: │arid │ ali@10: │**************** INPUT **************** │ ali@10: │I am the very model of a modern Major-General, │ ali@10: │I've information vegetable, animal, and mineral, │ ali@10: │I know the kings of England, arid I quote the fights historical│ ali@10: │From Marathon to Waterloo, in order categorical; │ ali@10: │I'm very well acquainted, too, with matters mathematical, │ ali@10: │I understand equations, both the simple and quadratical, │ ali@10: │About binomial theorem I'm teeming with a lot o' news-- │ ali@10: │With many cheerful facts about the square of the hypotenuse. │ ali@10: │**************** EXPECTED **************** │ ali@10: │ │ ali@10: │I know the kings of England, arid I quote the fights historical│ ali@10: │ Line 3 column 29 - Query possible scanno arid │ ali@10: └───────────────────────────────────────────────────────────────┘ ali@10: ali@10: Caveats ali@10: ------- ali@10: ali@10: There is no support yet for testcases which are expected to fail.