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