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