chiark / gitweb /
Update manual style.
[mLib] / man / 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
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
27The
28.B test_run
29function is intended to be called from the
30.B main
31function of a test rig program to check that a particular function or
32suite of functions are running properly. The arguments
33.I argc
34and
35.I argv
36should just be the arguments given to
37.BR main .
38The
39.I def
40argument gives the name of the default file of test vectors to read.
41This can be overridden at run-time by passing the program a
42.B \-f
43command-line option. The
44.I chunk
45argument is (the address of) an array of
46.I "chunk definitions"
47describing the layout of the test vector file.
48.SS "Test vector file syntax"
49Test vector files are mostly free-form. Comments begin with a hash
50.RB (` # ')
51and extend to the end of the line. Apart from that, newline characters
52are just considered to be whitespace.
53.PP
54Test 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
72Briefly in English: a test vector file is divided into chunks, each of
73which consists of a textual name and a brace-enclosed list of test
74vectors. Each test vector consists of a number of values terminated by
75a semicolon.
76.PP
77A value is either a sequence of
78.I "word characters"
79(alphanumerics and some other characters)
80or a string enclosed in quote marks (double or single). Quoted strings
81may contain newlines. In either type of value, a backslash escapes the
82following character.
83.SS "Chunk definitions"
84The caller must supply an array of one or more
85.IR "chunk definitions" .
86Each one describes the format of a named chunk: the number and type of
87the values required and the function to call in order to test the system
88against that test vector. The array is terminated by a chunk definition
89whose name field is a null pointer.
90.PP
91A chunk definition is described by the following structure:
92.VS
93typedef 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
99The members of this structure are as follows:
100.TP
ff76c38f 101.B "const char *name"
05fbeb03 102The name of the chunk described by this chunk definition, or null if
103this is the termination marker.
104.TP
ff76c38f 105.B "int (*test)(dstr dv[])"
05fbeb03 106The test function. It is passed an array of dynamic strings, one for
107each field, and must return nonzero if the test succeeded or zero if the
108test failed. On success, the function should not write anything to
109stdout or stderr; on failure, a report of the test arguments should be
110emitted to stderr.
111.TP
ff76c38f 112.B "test_type *f[TEST_FIELDMAX]"
05fbeb03 113Definitions of the fields. This is an array of pointers to
114.I "field types"
115(see below), terminated by a null pointer.
116.PP
117When the test driver encounters a chunk it has a definition for, it
118reads test vectors one by one, translating each value according to the
119designated field type, and then passing the completed array of fields to
120the test function.
121.SS "Field types"
122A field type describes how a field is to be read and written. A field
123type is described by a structure:
124.VS
125typedef struct test_type {
126 void (*cvt)(const char *buf, dstr *d);
127 void (*dump)(dstr *d, FILE *fp);
128} test_type;
129.VE
130The
ff76c38f 131.B cvt
05fbeb03 132member is a function called to read an input string stored in
ff76c38f 133.B buf
05fbeb03 134and output internal-format data in the dynamic string
135.IR d .
136The testrig driver has already stripped of quotes and dealt with
137backslash escapes.
138The
ff76c38f 139.B dump
05fbeb03 140member is called to write the internal-format data in dynamic string
141.I d
142to the
143.B stdio
144stream
145.IR fp .
146.PP
147There are three predefined field types:
148.TP
149.B "type_string"
150The simplest type. The string contents is not interpreted at all.
151.TP
152.B "type_hex"
153The string is interpreted as binary data encoded as hexadecimal.
154.TP
155.B "type_int"
156The string is interpreted as a textual representation of an integer.
157The integer is written to the dynamic string, and can be read out again
158with the expression
159.VS
160*(int *)d.buf
161.VE
162which isn't pretty but does the job.
dadc1afb 163.TP
164.B "type_long"
165As for
166.B type_int
167but reads and stores a
168.B long
169instead.
170.TP
171.B "type_ulong"
172As for
173.B type_long
174but reads and stores an
175.B "unsigned long"
176instead.
177.TP
178.B "type_uint32"
179As for
180.B type_int
181but reads and stores a
182.B uint32
183(see
184.BR bits (3))
185instead.
05fbeb03 186.SH "SEE ALSO"
187.BR mLib (3).
188.SH "AUTHOR"
189Mark Wooding, <mdw@nsict.org>