X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/d4efbcd93c940ad522fcf8c601ec1829d2e0b10d..9fcce036ef8b14c12fc4482efc7c8cf75da3b31f:/man/testrig.3

diff --git a/man/testrig.3 b/man/testrig.3
index c010cb0..b996617 100644
--- a/man/testrig.3
+++ b/man/testrig.3
@@ -19,17 +19,50 @@ testrig \- generic test rig
 .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
@@ -55,13 +88,18 @@ Test vector files have the following syntax:
 .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
@@ -80,13 +118,30 @@ A value is either a sequence of
 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