14 .TH testrig 3 "5 June 1999" mLib
16 testrig \- generic test rig
20 .B "#include <mLib/testrig.h>"
22 .BI "void test_run(int " argc ", char *" argv [],
23 .BI " const test_chunk " chunk [],
24 .BI " const char *" def );
29 function is intended to be called from the
31 function of a test rig program to check that a particular function or
32 suite of functions are running properly. The arguments
36 should just be the arguments given to
40 argument gives the name of the default file of test vectors to read.
41 This can be overridden at run-time by passing the program a
43 command-line option. The
45 argument is (the address of) an array of
46 .I "chunk definitions"
47 describing the layout of the test vector file.
48 .SS "Test vector file syntax"
49 Test vector files are mostly free-form. Comments begin with a hash
51 and extend to the end of the line. Apart from that, newline characters
52 are just considered to be whitespace.
54 Test vector files have the following syntax:
64 .RI [ test-vector ...]
72 Briefly in English: a test vector file is divided into chunks, each of
73 which consists of a textual name and a brace-enclosed list of test
74 vectors. Each test vector consists of a number of values terminated by
77 A value is either a sequence of
79 (alphanumerics and some other characters)
80 or a string enclosed in quote marks (double or single). Quoted strings
81 may contain newlines. In either type of value, a backslash escapes the
83 .SS "Chunk definitions"
84 The caller must supply an array of one or more
85 .IR "chunk definitions" .
86 Each one describes the format of a named chunk: the number and type of
87 the values required and the function to call in order to test the system
88 against that test vector. The array is terminated by a chunk definition
89 whose name field is a null pointer.
91 A chunk definition is described by the following structure:
93 typedef struct test_chunk {
94 const char *name; /* Name of this chunk */
95 int (*test)(dstr dv[]); /* Test verification function */
96 test_type *f[TEST_FIELDMAX]; /* Field definitions */
99 The members of this structure are as follows:
101 .B "const char *name"
102 The name of the chunk described by this chunk definition, or null if
103 this is the termination marker.
105 .B "int (*test)(dstr dv[])"
106 The test function. It is passed an array of dynamic strings, one for
107 each field, and must return nonzero if the test succeeded or zero if the
108 test failed. On success, the function should not write anything to
109 stdout or stderr; on failure, a report of the test arguments should be
112 .B "test_type *f[TEST_FIELDMAX]"
113 Definitions of the fields. This is an array of pointers to
115 (see below), terminated by a null pointer.
117 When the test driver encounters a chunk it has a definition for, it
118 reads test vectors one by one, translating each value according to the
119 designated field type, and then passing the completed array of fields to
122 A field type describes how a field is to be read and written. A field
123 type is described by a structure:
125 typedef struct test_type {
126 void (*cvt)(const char *buf, dstr *d);
127 void (*dump)(dstr *d, FILE *fp);
132 member is a function called to read an input string stored in
134 and output internal-format data in the dynamic string
136 The testrig driver has already stripped of quotes and dealt with
140 member is called to write the internal-format data in dynamic string
147 There are three predefined field types:
150 The simplest type. The string contents is not interpreted at all.
153 The string is interpreted as binary data encoded as hexadecimal.
156 The string is interpreted as a textual representation of an integer.
157 The integer is written to the dynamic string, and can be read out again
162 which isn't pretty but does the job.
167 but reads and stores a
174 but reads and stores an
181 but reads and stores a
189 Mark Wooding, <mdw@nsict.org>