*/*.3: Align arguments properly to the right of the opening `('.

[mLib] / test / testrig.3

.\" -*-nroff-*-
.de VS
.sp 1
.in +5
.nf
.ft B
..
.de VE
.ft R
.fi
.in -5
.sp 1
..
.TH testrig 3 "5 June 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
testrig \- generic test rig
.\" @test_run
.SH SYNOPSIS
.nf
.B "#include <mLib/testrig.h>"

.ds mT \fBint test_do(
.BI "\*(mTconst test_suite " suite [],
.BI "\h'\w'\*(mT'u'FILE *" fp ,
.BI "\h'\w'\*(mT'u'test_results *" results );
.ds mT \fBvoid test_run(
.BI "\*(mTint " argc ", char *" argv [],
.BI "\h'\w'\*(mT'u'const test_chunk " chunk [],
.BI "\h'\w'\*(mT'u'const char *" def );
.fi
.SH DESCRIPTION
.SS Structure
Test vectors are gathered together into
.I chunks
which should be processed in the same way.  Chunks, in turn, are grouped
into
.IR suites .
.SS Functions
The
.B test_do
function runs a collection of tests, as defined by
.IR suite ,
given the test vectors in the file
.IR fp .
It returns results in the
.B test_results
structure
.IR results ,
which has two members:
.TP
.B "unsigned tests"
counts the number of tests carried out, and
.TP
.B "unsigned failed"
counts the number of tests which failed.
.PP
The function returns negative if there was a system error or the test
vector file was corrupt in some way, zero if all the tests were
successful, or positive if some tests failed.
.PP
The
.B test_run
provides a simple command-line interface to the test system.  It is
intended to be called from the
.B main
function of a test rig program to check that a particular function or
suite of functions are running properly.  It does not return.  The arguments
.I argc
and
.I argv
should just be the arguments given to
.BR main .
The
.I def
argument gives the name of the default file of test vectors to read.
This can be overridden at run-time by passing the program a
.B \-f
command-line option.  The
.I chunk
argument is (the address of) an array of
.I "chunk definitions"
describing the layout of the test vector file.
.SS "Test vector file syntax"
Test vector files are mostly free-form.  Comments begin with a hash
.RB (` # ')
and extend to the end of the line.  Apart from that, newline characters
are just considered to be whitespace.
.PP
Test vector files have the following syntax:
.PP
.I file
::=
.RI [ suite-header | chunk " ...]"
.br
.I suite-header
::=
.B suite
.I name
.br
.I chunk
::=
.I name
.B {
.RI [ test-vector " ...]"
.B }
.br
.I test-vector
::=
.RI [ value ...]
.B ;
.PP
Briefly in English: a test vector file is divided into chunks, each of
which consists of a textual name and a brace-enclosed list of test
vectors.  Each test vector consists of a number of values terminated by
a semicolon.
.PP
A value is either a sequence of
.I "word characters"
(alphanumerics and some other characters)
or a string enclosed in quote marks (double or single).  Quoted strings
may contain newlines.  In either type of value, a backslash escapes the
following character.
.SS "Suite definitions"
A
.I suite definition
is described by the structure
.VS
typedef struct test_suite {
  const char *name;             /* Name of this suite */
  const test_chunk *chunks;     /* Pointer to chunks */
} test_suite;
.VE
The
.I suite
argument to
.B test_do
is a pointer to an array of these structures, terminated by one with a
null
.BR name .
.SS "Chunk definitions"
A
.I "chunk definition"
describes the format of a named chunk: the number and type of the values
required and the function to call in order to test the system against
that test vector.  The array is terminated by a chunk definition whose
name field is a null pointer.
.PP
A chunk definition is described by the following structure:
.VS
typedef struct test_chunk {
  const char *name;             /* Name of this chunk */
  int (*test)(dstr dv[]);       /* Test verification function */
  test_type *f[TEST_FIELDMAX];  /* Field definitions */
} test_chunk;
.VE
The members of this structure are as follows:
.TP
.B "const char *name"
The name of the chunk described by this chunk definition, or null if
this is the termination marker.
.TP
.B "int (*test)(dstr dv[])"
The test function.  It is passed an array of dynamic strings, one for
each field, and must return nonzero if the test succeeded or zero if the
test failed.  On success, the function should not write anything to
stdout or stderr; on failure, a report of the test arguments should be
emitted to stderr.
.TP
.B "test_type *f[TEST_FIELDMAX]"
Definitions of the fields.  This is an array of pointers to
.I "field types"
(see below), terminated by a null pointer.
.PP
When the test driver encounters a chunk it has a definition for, it
reads test vectors one by one, translating each value according to the
designated field type, and then passing the completed array of fields to
the test function.
.SS "Field types"
A field type describes how a field is to be read and written.  A field
type is described by a structure:
.VS
typedef struct test_type {
  void (*cvt)(const char *buf, dstr *d);
  void (*dump)(dstr *d, FILE *fp);
} test_type;
.VE
The
.B cvt
member is a function called to read an input string stored in
.B buf
and output internal-format data in the dynamic string
.IR d .
The testrig driver has already stripped of quotes and dealt with
backslash escapes.
The
.B dump
member is called to write the internal-format data in dynamic string
.I d
to the
.B stdio
stream
.IR fp .
.PP
There are three predefined field types:
.TP
.B "type_string"
The simplest type.  The string contents is not interpreted at all.
.TP
.B "type_hex"
The string is interpreted as binary data encoded as hexadecimal.
.TP
.B "type_int"
The string is interpreted as a textual representation of an integer.
The integer is written to the dynamic string, and can be read out again
with the expression
.VS
*(int *)d.buf
.VE
which isn't pretty but does the job.
.TP
.B "type_long"
As for
.B type_int
but reads and stores a
.B long
instead.
.TP
.B "type_ulong"
As for
.B type_long
but reads and stores an
.B "unsigned long"
instead.
.TP
.B "type_uint32"
As for
.B type_int
but reads and stores a
.B uint32
(see
.BR bits (3))
instead.
.SH "SEE ALSO"
.BR mLib (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>