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