testrig: Provide useful interface for more complicated test rigs.

[mLib] / man / testrig.3

diff --git a/man/testrig.3 b/man/testrig.3
index c010cb04378ac5919c59851f75ae954ea0f7fbf3..b996617e7a6a205b63267ccc31eff076c2d7f01c 100644 (file)
--- a/man/testrig.3
+++ b/man/testrig.3
@@ -19,17 +19,50 @@ testrig \- generic test rig
 .nf
 .B "#include <mLib/testrig.h>"
 
 .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
 .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
 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
 .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
 .I argc
 and
 .I argv


@@ -55,13 +88,18 @@ Test vector files have the following syntax:
 .PP
 .I file
 ::=
 .PP
 .I file
 ::=

-.RI [ chunk ...]
+.RI [ suite-header | chunk " ...]"
+.br
+.I suite-header
+::=
+.B suite
+.I name

 .br
 .I chunk
 ::=
 .I name
 .B {
 .br
 .I chunk
 ::=
 .I name
 .B {

-.RI [ test-vector ...]
+.RI [ test-vector " ...]"

 .B }
 .br
 .I 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.
 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"
 .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
 .PP
 A chunk definition is described by the following structure:
 .VS