.nf
.B "#include <mLib/testrig.h>"
+.BI "void test_do(const test_suite " suite [],
+.BI " FILE *" fp ,
+.BI " test_results *" results );
.BI "void test_run(int " argc ", char *" argv [],
.BI " const test_chunk " chunk [],
.BI " 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
-function is intended to be called from the
+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. The arguments
+suite of functions are running properly. It does not return. The arguments
.I argc
and
.I argv
.PP
.I file
::=
-.RI [ chunk ...]
+.RI [ suite-header | chunk " ...]"
+.br
+.I suite-header
+::=
+.B suite
+.I name
.br
.I chunk
::=
.I name
.B {
-.RI [ test-vector ...]
+.RI [ test-vector " ...]"
.B }
.br
.I test-vector
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"
-The caller must supply an array of one or more
-.IR "chunk definitions" .
-Each one 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.
+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