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

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