05fbeb03 |
1 | .\" -*-nroff-*- |
2 | .de VS |
3 | .sp 1 |
4 | .in +5 |
5 | .nf |
6 | .ft B |
7 | .. |
8 | .de VE |
9 | .ft R |
10 | .fi |
11 | .in -5 |
12 | .sp 1 |
13 | .. |
05fbeb03 |
14 | .TH testrig 3 "5 June 1999" mLib |
15 | .SH NAME |
16 | testrig \- generic test rig |
17 | .\" @test_run |
18 | .SH SYNOPSIS |
19 | .nf |
20 | .B "#include <mLib/testrig.h>" |
21 | |
22 | .BI "void test_run(int " argc ", char *" argv [], |
23 | .BI " const test_chunk " chunk [], |
24 | .BI " const char *" def ); |
25 | .fi |
26 | .SH DESCRIPTION |
27 | The |
28 | .B test_run |
29 | function is intended to be called from the |
30 | .B main |
31 | function of a test rig program to check that a particular function or |
32 | suite of functions are running properly. The arguments |
33 | .I argc |
34 | and |
35 | .I argv |
36 | should just be the arguments given to |
37 | .BR main . |
38 | The |
39 | .I def |
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 |
42 | .B \-f |
43 | command-line option. The |
44 | .I chunk |
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 |
50 | .RB (` # ') |
51 | and extend to the end of the line. Apart from that, newline characters |
52 | are just considered to be whitespace. |
53 | .PP |
54 | Test vector files have the following syntax: |
55 | .PP |
56 | .I file |
57 | ::= |
58 | .RI [ chunk ...] |
59 | .br |
60 | .I chunk |
61 | ::= |
62 | .I name |
63 | .B { |
64 | .RI [ test-vector ...] |
65 | .B } |
66 | .br |
67 | .I test-vector |
68 | ::= |
69 | .RI [ value ...] |
70 | .B ; |
71 | .PP |
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 |
75 | a semicolon. |
76 | .PP |
77 | A value is either a sequence of |
78 | .I "word characters" |
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 |
82 | following character. |
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. |
90 | .PP |
91 | A chunk definition is described by the following structure: |
92 | .VS |
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 */ |
97 | } test_chunk; |
98 | .VE |
99 | The members of this structure are as follows: |
100 | .TP |
ff76c38f |
101 | .B "const char *name" |
05fbeb03 |
102 | The name of the chunk described by this chunk definition, or null if |
103 | this is the termination marker. |
104 | .TP |
ff76c38f |
105 | .B "int (*test)(dstr dv[])" |
05fbeb03 |
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 |
110 | emitted to stderr. |
111 | .TP |
ff76c38f |
112 | .B "test_type *f[TEST_FIELDMAX]" |
05fbeb03 |
113 | Definitions of the fields. This is an array of pointers to |
114 | .I "field types" |
115 | (see below), terminated by a null pointer. |
116 | .PP |
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 |
120 | the test function. |
121 | .SS "Field types" |
122 | A field type describes how a field is to be read and written. A field |
123 | type is described by a structure: |
124 | .VS |
125 | typedef struct test_type { |
126 | void (*cvt)(const char *buf, dstr *d); |
127 | void (*dump)(dstr *d, FILE *fp); |
128 | } test_type; |
129 | .VE |
130 | The |
ff76c38f |
131 | .B cvt |
05fbeb03 |
132 | member is a function called to read an input string stored in |
ff76c38f |
133 | .B buf |
05fbeb03 |
134 | and output internal-format data in the dynamic string |
135 | .IR d . |
136 | The testrig driver has already stripped of quotes and dealt with |
137 | backslash escapes. |
138 | The |
ff76c38f |
139 | .B dump |
05fbeb03 |
140 | member is called to write the internal-format data in dynamic string |
141 | .I d |
142 | to the |
143 | .B stdio |
144 | stream |
145 | .IR fp . |
146 | .PP |
147 | There are three predefined field types: |
148 | .TP |
149 | .B "type_string" |
150 | The simplest type. The string contents is not interpreted at all. |
151 | .TP |
152 | .B "type_hex" |
153 | The string is interpreted as binary data encoded as hexadecimal. |
154 | .TP |
155 | .B "type_int" |
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 |
158 | with the expression |
159 | .VS |
160 | *(int *)d.buf |
161 | .VE |
162 | which isn't pretty but does the job. |
dadc1afb |
163 | .TP |
164 | .B "type_long" |
165 | As for |
166 | .B type_int |
167 | but reads and stores a |
168 | .B long |
169 | instead. |
170 | .TP |
171 | .B "type_ulong" |
172 | As for |
173 | .B type_long |
174 | but reads and stores an |
175 | .B "unsigned long" |
176 | instead. |
177 | .TP |
178 | .B "type_uint32" |
179 | As for |
180 | .B type_int |
181 | but reads and stores a |
182 | .B uint32 |
183 | (see |
184 | .BR bits (3)) |
185 | instead. |
05fbeb03 |
186 | .SH "SEE ALSO" |
187 | .BR mLib (3). |
188 | .SH "AUTHOR" |
189 | Mark Wooding, <mdw@nsict.org> |