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