14 .TH testrig 3 "5 June 1999" "Straylight/Edgeware" "mLib utilities library"
16 testrig \- generic test rig
20 .B "#include <mLib/testrig.h>"
22 .B "#define TEST_FIELDMAX ..."
25 .B "\h'4n'unsigned tests, failed;"
29 .BI "\h'4n'void (*cvt)(const char *" buf ", dstr *" d );
30 .BI "\h'4n'void (*dump)(dstr *" d ", FILE *" fp );
34 .B "\h'4n'const char *name;"
35 .BI "\h'4n'void (*test)(dstr " dv "[]);"
36 .B "\h'4n'const test_type *f[TEST_FIELDMAX];"
40 .B "\h'4n'const char *name;"
41 .B "\h'4n'const test_chunk *chunks;"
44 .B "const test_type type_hex;"
45 .B "const test_type type_string;"
46 .B "const test_type type_int;"
47 .B "const test_type type_long;"
48 .B "const test_type type_ulong;"
49 .B "const test_type type_uint32;"
51 .ds mT \fBint test_do(
52 .BI "\*(mTconst test_suite " suite [],
53 .BI "\h'\w'\*(mT'u'FILE *" fp ,
54 .BI "\h'\w'\*(mT'u'test_results *" results );
55 .ds mT \fBvoid test_run(
56 .BI "\*(mTint " argc ", char *" argv [],
57 .BI "\h'\w'\*(mT'u'const test_chunk " chunk [],
58 .BI "\h'\w'\*(mT'u'const char *" def );
62 Test vectors are gathered together into
64 which should be processed in the same way. Chunks, in turn, are grouped
70 function runs a collection of tests, as defined by
72 given the test vectors in the file
74 It returns results in the
78 which has two members:
81 counts the number of tests carried out, and
84 counts the number of tests which failed.
86 The function returns negative if there was a system error or the test
87 vector file was corrupt in some way, zero if all the tests were
88 successful, or positive if some tests failed.
92 provides a simple command-line interface to the test system. It is
93 intended to be called from the
95 function of a test rig program to check that a particular function or
96 suite of functions are running properly. It does not return. The arguments
100 should just be the arguments given to
104 argument gives the name of the default file of test vectors to read.
105 This can be overridden at run-time by passing the program a
107 command-line option. The
109 argument is (the address of) an array of
110 .I "chunk definitions"
111 describing the layout of the test vector file.
112 .SS "Test vector file syntax"
113 Test vector files are mostly free-form. Comments begin with a hash
115 and extend to the end of the line. Apart from that, newline characters
116 are just considered to be whitespace.
118 Test vector files have the following syntax:
122 .RI [ suite-header | chunk " ...]"
133 .RI [ test-vector " ...]"
141 Briefly in English: a test vector file is divided into chunks, each of
142 which consists of a textual name and a brace-enclosed list of test
143 vectors. Each test vector consists of a number of values terminated by
146 A value is either a sequence of
148 (alphanumerics and some other characters)
149 or a string enclosed in quote marks (double or single). Quoted strings
150 may contain newlines. In either type of value, a backslash escapes the
152 .SS "Suite definitions"
161 is a pointer to an array of these structures, terminated by one with a
164 .SS "Chunk definitions"
166 .I "chunk definition"
167 describes the format of a named chunk: the number and type of the values
168 required and the function to call in order to test the system against
169 that test vector. The array is terminated by a chunk definition whose
170 name field is a null pointer.
172 A chunk definition is described by the
174 structure. The members of this structure are as follows:
176 .B "const char *name"
177 The name of the chunk described by this chunk definition, or null if
178 this is the termination marker.
180 .BI "int (*test)(dstr " dv "[])"
181 The test function. It is passed an array of dynamic strings, one for
182 each field, and must return nonzero if the test succeeded or zero if the
183 test failed. On success, the function should not write anything to
184 stdout or stderr; on failure, a report of the test arguments should be
187 .B "test_type *f[TEST_FIELDMAX]"
188 Definitions of the fields. This is an array of pointers to
190 (see below), terminated by a null pointer.
192 When the test driver encounters a chunk it has a definition for, it
193 reads test vectors one by one, translating each value according to the
194 designated field type, and then passing the completed array of fields to
197 A field type describes how a field is to be read and written. A field
198 type is described by a
202 member is a function called to read an input string stored in
204 and output internal-format data in the dynamic string
206 The testrig driver has already stripped of quotes and dealt with
210 member is called to write the internal-format data in dynamic string
217 There are three predefined field types:
220 The simplest type. The string contents is not interpreted at all.
223 The string is interpreted as binary data encoded as hexadecimal.
226 The string is interpreted as a textual representation of an integer.
227 The integer is written to the dynamic string, and can be read out again
232 which isn't pretty but does the job.
237 but reads and stores a
244 but reads and stores an
251 but reads and stores a
259 Mark Wooding, <mdw@distorted.org.uk>