chiark - git - mdw - mLib/blob - test/testrig.3

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