.
.\"--------------------------------------------------------------------------
.TH tvec 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.
-.\"--------------------------------------------------------------------------
-.SH NAME
-tvec \- test vector framework
.\" @tvec_begin
.\" @tvec_end
.\" @tvec_read
.\" @tvec_dfltoutput
.
.\"--------------------------------------------------------------------------
+.SH NAME
+tvec \- test vector framework
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.nf
.B "#include <mLib/tvec.h>"
against which the test function's outputs are to be checked.
.PP
The test function is called with two vectors of registers,
-one containing input values for the test function to read,
+one containing input values for the test function to read
+and also reference output values,
and another for output values that the test function should write;
and a
.I context
for a single test.
The
.I reg
-name in an assignment must match the name of an active register;
+name in an assignment must match the name
+of an active register or a
+.I "special variable" ;
the corresponding
.I value
-is stored in the named register.
+is stored in the named register or variable.
+.PP
+A register which has been assigned a value is said to be
+.IR live ;
+otherwise, it is
+.IR dead .
+By default, every active register must be live for a test to proceed;
+but a register definition can mark its register as
+.I optional
+or
+.IR may-be-unset .
+An optional register need not be assigned a value explicitly;
+instead, the register is left dead.
+A may-be-unset register must be mentioned,
+but a distinctive syntax
+.IP
+.IB reg " *"
+.PP
+(with no colon or equals sign)
+says that the register should be left dead.
+Optional registers are suitable for cases where
+there is an obvious default value
+which would otherwise be mentioned frequently in input files.
+May-be-unset registers are mostly useful as outputs,
+where the output is not always set,
+e.g., in error cases,
+but where omitting a value in the usual case is likely a mistake.
.PP
A test environment fits in between
the framework and the test function.
It can establish hook functions which are called
-at various stages during the test group.
+at various points throughout a test group
+(at the start and and, and before and after each test).
+It can define special variables
+which can be set from the input file using assignments.
+And, finally, it can take on the responsibility
+of running the test function.
+The registers will have been set up already,
+based on the assignments in the input file,
+but the environment can modify them.
+It must also check the test function's output
+against the reference values,
+though there are functions provided for doing this.
+The environment can choose to run the test function once,
+multiple times, or, indeed, not at all.
+When it calls the test function, it can provide a context pointer,
+with whatever additional information might be useful:
+this usually involves coordination
+between the environment and the test function.
+It is the test environment's responsibility
+to check the outputs returned by the test function
+and to report on mismatches,
+but there are functions provided by the framework
+to do the heavy lifting.
+.PP
+The following are examples of what test environments can do.
.hP \*o
-The
-.I setup
-hook is called once at the start of the test group.
+It can fill in default values for optional dead registers.
+For example, if a function returnns error codes,
+then you can save reptition in the input file
+by marking the error-code output register optional
+and letting it default to the `success' value in a test environment.
+.hP \*o
+It can run the test function mulitple times.
+For example, a test of functions like
+.BR strcmp (3)
+might run the test twice,
+first with its operands as supplied by the input file,
+and then again with the operands swapped
+and the opposite expected result.
+A test for bignum addition could verify commutativity
+by checking both that
+.IR x "\ + \ " y "\ =\ " z
+and that
+.IR y "\ + \ " x "\ =\ " z \fR.
+Similarly, a subtraction test could check both that
+.IR x "\ \- \ " y "\ =\ " z
+and that
+.IR y "\ \- \ " x "\ =\ \-" z \fR.
.hP \*o
The
-.I teardown
-hook is called once at the end of the test group.
+.BR tvec-remote (3),
+.BR tvec-timeout (3),
+and
+.BR tvec-bench (3)
+extensions all slot in as test environments.
+Sadly,
+.BR tvec-bench (3)
+requires support from the output protocol
+in order to format benchmark results properly;
+apart from that,
+these three facilities are pure extensions
~mdw / mLib / blobdiff