17 \h'-\w'\\$1\ 'u'\\$1\ \c
22 .TH testrig 3 "5 June 1999" mLib
24 testrig \- generic test rig
28 .B "#include <mLib/testrig.h>"
30 .BI "void test_run(int " argc ", char *" argv [],
31 .BI " const test_chunk " chunk [],
32 .BI " const char *" def );
37 function is intended to be called from the
39 function of a test rig program to check that a particular function or
40 suite of functions are running properly. The arguments
44 should just be the arguments given to
48 argument gives the name of the default file of test vectors to read.
49 This can be overridden at run-time by passing the program a
51 command-line option. The
53 argument is (the address of) an array of
54 .I "chunk definitions"
55 describing the layout of the test vector file.
56 .SS "Test vector file syntax"
57 Test vector files are mostly free-form. Comments begin with a hash
59 and extend to the end of the line. Apart from that, newline characters
60 are just considered to be whitespace.
62 Test vector files have the following syntax:
72 .RI [ test-vector ...]
80 Briefly in English: a test vector file is divided into chunks, each of
81 which consists of a textual name and a brace-enclosed list of test
82 vectors. Each test vector consists of a number of values terminated by
85 A value is either a sequence of
87 (alphanumerics and some other characters)
88 or a string enclosed in quote marks (double or single). Quoted strings
89 may contain newlines. In either type of value, a backslash escapes the
91 .SS "Chunk definitions"
92 The caller must supply an array of one or more
93 .IR "chunk definitions" .
94 Each one describes the format of a named chunk: the number and type of
95 the values required and the function to call in order to test the system
96 against that test vector. The array is terminated by a chunk definition
97 whose name field is a null pointer.
99 A chunk definition is described by the following structure:
101 typedef struct test_chunk {
102 const char *name; /* Name of this chunk */
103 int (*test)(dstr dv[]); /* Test verification function */
104 test_type *f[TEST_FIELDMAX]; /* Field definitions */
107 The members of this structure are as follows:
110 The name of the chunk described by this chunk definition, or null if
111 this is the termination marker.
114 The test function. It is passed an array of dynamic strings, one for
115 each field, and must return nonzero if the test succeeded or zero if the
116 test failed. On success, the function should not write anything to
117 stdout or stderr; on failure, a report of the test arguments should be
121 Definitions of the fields. This is an array of pointers to
123 (see below), terminated by a null pointer.
125 When the test driver encounters a chunk it has a definition for, it
126 reads test vectors one by one, translating each value according to the
127 designated field type, and then passing the completed array of fields to
130 A field type describes how a field is to be read and written. A field
131 type is described by a structure:
133 typedef struct test_type {
134 void (*cvt)(const char *buf, dstr *d);
135 void (*dump)(dstr *d, FILE *fp);
140 member is a function called to read an input string stored in
142 and output internal-format data in the dynamic string
144 The testrig driver has already stripped of quotes and dealt with
148 member is called to write the internal-format data in dynamic string
155 There are three predefined field types:
158 The simplest type. The string contents is not interpreted at all.
161 The string is interpreted as binary data encoded as hexadecimal.
164 The string is interpreted as a textual representation of an integer.
165 The integer is written to the dynamic string, and can be read out again
170 which isn't pretty but does the job.
174 Mark Wooding, <mdw@nsict.org>