chiark / gitweb /
Commit as 2.1.0.
[mLib] / testrig.3
CommitLineData
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..
fbf20b5b 14.TH testrig 3 "5 June 1999" "Straylight/Edgeware" "mLib utilities library"
05fbeb03 15.SH NAME
16testrig \- generic test rig
17.\" @test_run
18.SH SYNOPSIS
19.nf
20.B "#include <mLib/testrig.h>"
21
9fcce036
MW
22.BI "void test_do(const test_suite " suite [],
23.BI " FILE *" fp ,
24.BI " test_results *" results );
05fbeb03 25.BI "void test_run(int " argc ", char *" argv [],
26.BI " const test_chunk " chunk [],
27.BI " const char *" def );
28.fi
29.SH DESCRIPTION
9fcce036
MW
30.SS Structure
31Test vectors are gathered together into
32.I chunks
33which should be processed in the same way. Chunks, in turn, are grouped
34into
35.IR suites .
36.SS Functions
37The
38.B test_do
39function runs a collection of tests, as defined by
40.IR suite ,
41given the test vectors in the file
42.IR fp .
43It returns results in the
44.B test_results
45structure
46.IR results ,
47which has two members:
48.TP
49.B "unsigned tests"
50counts the number of tests carried out, and
51.TP
52.B "unsigned failed"
53counts the number of tests which failed.
54.PP
55The function returns negative if there was a system error or the test
56vector file was corrupt in some way, zero if all the tests were
57successful, or positive if some tests failed.
58.PP
05fbeb03 59The
60.B test_run
9fcce036
MW
61provides a simple command-line interface to the test system. It is
62intended to be called from the
05fbeb03 63.B main
64function of a test rig program to check that a particular function or
9fcce036 65suite of functions are running properly. It does not return. The arguments
05fbeb03 66.I argc
67and
68.I argv
69should just be the arguments given to
70.BR main .
71The
72.I def
73argument gives the name of the default file of test vectors to read.
74This can be overridden at run-time by passing the program a
75.B \-f
76command-line option. The
77.I chunk
78argument is (the address of) an array of
79.I "chunk definitions"
80describing the layout of the test vector file.
81.SS "Test vector file syntax"
82Test vector files are mostly free-form. Comments begin with a hash
83.RB (` # ')
84and extend to the end of the line. Apart from that, newline characters
85are just considered to be whitespace.
86.PP
87Test vector files have the following syntax:
88.PP
89.I file
90::=
9fcce036
MW
91.RI [ suite-header | chunk " ...]"
92.br
93.I suite-header
94::=
95.B suite
96.I name
05fbeb03 97.br
98.I chunk
99::=
100.I name
101.B {
9fcce036 102.RI [ test-vector " ...]"
05fbeb03 103.B }
104.br
105.I test-vector
106::=
107.RI [ value ...]
108.B ;
109.PP
110Briefly in English: a test vector file is divided into chunks, each of
111which consists of a textual name and a brace-enclosed list of test
112vectors. Each test vector consists of a number of values terminated by
113a semicolon.
114.PP
115A value is either a sequence of
116.I "word characters"
117(alphanumerics and some other characters)
118or a string enclosed in quote marks (double or single). Quoted strings
119may contain newlines. In either type of value, a backslash escapes the
120following character.
9fcce036
MW
121.SS "Suite definitions"
122A
123.I suite definition
124is described by the structure
125.VS
126typedef struct test_suite {
127 const char *name; /* Name of this suite */
128 const test_chunk *chunks; /* Pointer to chunks */
129} test_suite;
130.VE
131The
132.I suite
133argument to
134.B test_do
135is a pointer to an array of these structures, terminated by one with a
136null
137.BR name .
05fbeb03 138.SS "Chunk definitions"
9fcce036
MW
139A
140.I "chunk definition"
141describes the format of a named chunk: the number and type of the values
142required and the function to call in order to test the system against
143that test vector. The array is terminated by a chunk definition whose
144name field is a null pointer.
05fbeb03 145.PP
146A chunk definition is described by the following structure:
147.VS
148typedef struct test_chunk {
149 const char *name; /* Name of this chunk */
150 int (*test)(dstr dv[]); /* Test verification function */
151 test_type *f[TEST_FIELDMAX]; /* Field definitions */
152} test_chunk;
153.VE
154The members of this structure are as follows:
155.TP
ff76c38f 156.B "const char *name"
05fbeb03 157The name of the chunk described by this chunk definition, or null if
158this is the termination marker.
159.TP
ff76c38f 160.B "int (*test)(dstr dv[])"
05fbeb03 161The test function. It is passed an array of dynamic strings, one for
162each field, and must return nonzero if the test succeeded or zero if the
163test failed. On success, the function should not write anything to
164stdout or stderr; on failure, a report of the test arguments should be
165emitted to stderr.
166.TP
ff76c38f 167.B "test_type *f[TEST_FIELDMAX]"
05fbeb03 168Definitions of the fields. This is an array of pointers to
169.I "field types"
170(see below), terminated by a null pointer.
171.PP
172When the test driver encounters a chunk it has a definition for, it
173reads test vectors one by one, translating each value according to the
174designated field type, and then passing the completed array of fields to
175the test function.
176.SS "Field types"
177A field type describes how a field is to be read and written. A field
178type is described by a structure:
179.VS
180typedef struct test_type {
181 void (*cvt)(const char *buf, dstr *d);
182 void (*dump)(dstr *d, FILE *fp);
183} test_type;
184.VE
185The
ff76c38f 186.B cvt
05fbeb03 187member is a function called to read an input string stored in
ff76c38f 188.B buf
05fbeb03 189and output internal-format data in the dynamic string
190.IR d .
191The testrig driver has already stripped of quotes and dealt with
192backslash escapes.
193The
ff76c38f 194.B dump
05fbeb03 195member is called to write the internal-format data in dynamic string
196.I d
197to the
198.B stdio
199stream
200.IR fp .
201.PP
202There are three predefined field types:
203.TP
204.B "type_string"
205The simplest type. The string contents is not interpreted at all.
206.TP
207.B "type_hex"
208The string is interpreted as binary data encoded as hexadecimal.
209.TP
210.B "type_int"
211The string is interpreted as a textual representation of an integer.
212The integer is written to the dynamic string, and can be read out again
213with the expression
214.VS
215*(int *)d.buf
216.VE
217which isn't pretty but does the job.
dadc1afb 218.TP
219.B "type_long"
220As for
221.B type_int
222but reads and stores a
223.B long
224instead.
225.TP
226.B "type_ulong"
227As for
228.B type_long
229but reads and stores an
230.B "unsigned long"
231instead.
232.TP
233.B "type_uint32"
234As for
235.B type_int
236but reads and stores a
237.B uint32
238(see
239.BR bits (3))
240instead.
05fbeb03 241.SH "SEE ALSO"
242.BR mLib (3).
243.SH "AUTHOR"
9b5ac6ff 244Mark Wooding, <mdw@distorted.org.uk>