NAME
tst_res - Print result message, including file contents
tst_resm - Print result message
tst_brk - Print result message and break remaining test cases
tst_brkm - Print result message, including file contents, and break
remaining test cases
tst_brkloop - Print result message, include file contents, and break
remaining test cases in loop
tst_brkloopm - Print result message and break remaining test cases in
loop
tst_flush - Print any messages pending because of CONDENSE mode, and
flush output stream
tst_exit - Exit test with a meaningful exit value
tst_environ - Keep results coming to original stdout
SYNOPSIS
#include "test.h"
void tst_res(int ttype, char *fname, char *tmesg, [arg ...])
void tst_resm(int ttype, char *tmesg, [arg ...])
void tst_brk(int ttype, char *fname, void (*func)(), char *tmesg, [arg
...])
void tst_brkm(int ttype, void (*func)(), char *tmesg, [arg ...])
void tst_brkloop(int ttype, char *fname, void (*func)(), char *tmesg,
[arg ...])
void tst_brkloopm(int ttype, void (*func)(), char *tmesg, [arg ...])
void tst_flush()
void tst_exit()
int tst_environ()
extern int Tst_count;
extern int Tst_range;
extern int Tst_lpstart;
extern int Tst_lptotal;
DESCRIPTION
Introduction
This library of functions are used by UNICOS tests to report results to
standard out in a consistent manner. It is assumed that tests using
this library have a distinct number of test cases, and that each test
case is distinct and uniquely identified by the test case number. It
is also assumed that test case results are printed in consecutive
order, starting with 1. The library maintains a set of global
variables (TCID, TST_TOTAL, Tst_count, Tst_range, Tst_lpstart,
Tst_lptotal), which are used by the various functions to format the
results and to keep track of the current result reporting state (i.e.
how many total test cases there are, and how many have been reported so
far) for the calling test.
The TCID and TST_TOTAL global variables are externed in the library,
and MUST be defined/initialized by tests using the library. TCID must
be set to the Test Case IDentifier, and TST_TOTAL must be set to the
total number of test cases that will be reported.
The other global variables are available as externs to tests linked
with tst_res.o. Tst_count is the running count of the number of test
results that have been reported so far. The library initializes it to
0, and it should not be modified by the test. Tst_range, Tst_lpstart,
and Tst_lptotal are used by to control how many test results are
reported under certain conditions, by some of the functions in this
library. The details are described below under the appropriate
functions.
Arguments
ttype test result type; one of TPASS, TFAIL, TBROK, TCONF,
TRETR, TWARN, or TINFO (explained below).
fname pointer to a character string holding the name of a file
whose contents will be printed on a new line following
tmesg. If this pointer is NULL, it is ignored.
tmesg, [arg ...]
pointer to a character string containing a message
explaining the test result. This character string can
contain percent-sign conversion specifications as in
printf(3C) with corresponding arg arguments following
the tmesg argument.
NOTE: These routines use static space internally to hold
the expanded message. The maximum size allowed for an
expanded message is 2048 bytes.
func pointer to a function which performs either the cleanup
necessary prior to exiting the test or some function
executed at the end of each iteration of a loop.
Result Types
The possible test result types defined in test.h are as follows:
TPASS The test case produced expected results.
TFAIL The test case produced unexpected results.
TBROK A resource needed to execute the test case was not
available (e.g. a temporary file could not be opened).
TCONF The test case was not appropriate for the current
hardware or software configuration (e.g. MLS was not
enabled).
TRETR The test case was no longer valid and has been
"retired."
TWARN The testing procedure caused undesirable side effects
that did not affect test results (e.g. a temporary file
could not be removed after all test results were
recorded).
TINFO An informative message about the execution of the test
that does not correspond to a test case result and does
not indicate a problem.
Function Descriptions
tst_res() and tst_resm() are the basic result reporting functions.
They report 1 or more test case results of the specified ttype. All
result types are valid for these functions. The Tst_range global
variable indicates the number of results that will be reported for each
call to one of these functions. It is initialized by the library to 1,
but may be set to a value > 1 by the test. Each call to one of these
functions will result in Tst_range test case results being reported,
each with an identical message (tmesg). Tst_range is always reset to 1
by the library before returning to the caller. If tst_res() is called
with a fname argument, the contents of the file will only be printed
for the first reported result. tst_res() takes the fname argument
whereas tst_resm() does not.
NOTE: All calls to tst_res() specifying a ttype of TWARN or TINFO will
be printed with a test case number of zero. Because of this, a
Tst_range value > 1 is not valid for these types.
tst_brk() and tst_brkm() are used to report results for all test cases
remaining in the test, and then call a cleanup function. The only
result types that are valid for these functions are: TFAIL, TBROK,
TCONF, and TRETR. When called with a ttype of TFAIL or TBROK, one
result of the specified ttype will be printed, followed by results of
type TBROK for the remaining test cases. When called with a ttype of
TCONF or TRETR, the specified ttype will be printed for all remaining
test cases. If func is not NULL, tst_brk() and tst_brkm() will call
func after all results have been printed. If the call to func returns,
tst_brk() and tst_brkm() will then call tst_exit(). If func is NULL,
tst_brk() and tst_brkm() return to the caller after all results have
been printed. If tst_brk() is called with a fname argument, the
contents of the file will only be printed for the first reported
result. tst_brk() takes the fname argument whereas tst_brkm() does
not.
tst_brkloop() and tst_brkloopm() work just like tst_brk() and
tst_brkm(), except they only report results for a the test cases
remaining in the current loop. The Tst_lpstart and Tst_lptotal global
variables are used to determine how many test cases to report results
for. Prior to the start of the loop, the test must set Tst_lpstart to
Tst_count, and Tst_lptotal to the number of test cases in the loop. If
a test calls tst_brkloop() or tst_brkloopm() without first setting
Tst_lpstart and Tst_lptotal to meaningful values, a WARN result will be
reported and control will be immediately returned to the caller. This
will most likely cause the result messages to be out of order. Unlike
the tst_brk() functions, tst_brkloop() and tst_brkloopm() will not call
tst_exit() if the func argument is not NULL and returns. tst_brkloop()
takes the fname argument whereas tst_brkloopm() does not.
tst_flush() is used to print any results pending because of CONDENSE or
NOPASS modes (described below), and flushes the output stream.
tst_exit() is used to allow tests to exit with a meaningful exit value.
A bit is set in the exit value for each of the non passing test case
result types (TFAIL, TBROK, and TWARN) encountered by the library.
Thus any bit which is set in the exit value indicates that the
corresponding result flag was used at least once in the test run.
The current bit fields for the result types are as follows:
TPASS 0000 /* .... .... */
TFAIL 0001 /* .... ...1 */
TBROK 0002 /* .... ..1. */
TWARN 0004 /* .... .1.. */
TRETR 0010 /* .... 1... */
TINFO 0020 /* ...1 .... */
TCONF 0040 /* ..1. .... */
NOTE: TPASS, TRETR, TINFO, and TCONF do not have an effect on the test
program exit status.
tst_environ() is used to ensure that results reported by this library
will go to the original stdout, even if the test changes the original
stdout to another file, or closes it. A test may want to do this in
order to redirect output that normally goes to stdout (e.g. printf()
output) to a file. tst_environ() returns 0 upon successful completion,
and -1 if it encountered any problems.
Output Modes
Four output display modes are supported by the tst_res() family of
functions to enhance output readability. The active mode is controlled
via the environment variable TOUTPUT, which must be set prior to the
start of the test in order to have any effect (see ksh(1) for
information on environment variables). The supported modes are as
follows:
VERBOSE A test result output line is generated for each
test result. This is the default mode.
CONDENSE Consecutive, identical PASS, FAIL, BROK, CONF, and
RETR test results are condensed into one output
line. The test case number field contains the
range of results involved. WARN and INFO output
lines are not condensed, but printed as usual.
NOPASS All PASS, CONF, INFO, and RETR output lines are
discarded (i.e. not printed), and consecutive,
identical FAIL and BROK output lines are condensed
as in CONDENSE mode. WARN output lines are printed
as usual.
DISCARD All output lines are discarded.
EXAMPLES
#include "test.h"
char *TCID = "tsttcs01"; /* set test case identifier */
int TST_TOTAL = 15; /* set total number of test results */
extern int Tst_count; /* access count of results completed */
extern int Tst_lpstart; /* holds value for start of loop */
extern int Tst_lptotal; /* holds the number of test cases in loop */
main()
{
.
.
/* a successful test result */
tst_resm(TPASS, "what was tested");
/* or */
tst_res(TPASS, file, "what was tested");
.
.
/* break all remaining test results */
tst_brkm(TBROK, cleanup, "what didnt work");
/* or */
tst_brk(TBROK, file, cleanup, "what didnt work");
.
.
/* Break all remaining tests in loop */
Tst_lpstart = Tst_count;
Tst_lptotal = 5;
tst_brkloopm(TBROK, loop_setup, "setup did not work.");
/* or */
tst_brkloop(TBROK, file, loop_setup, "setup did not work.");
.
.
/* exit after all test results have been passed to tst_res */
tst_exit();
}
Sample output:
tsttcs01 1 PASS : Able to create MAXUP processes
tsttcs01 2 FAIL : Too many processes (MAXUP+1) created
tsttcs01 3 BROK : tabinfo(PROCTAB, &tbs) failed; errno = 13: Permission denied
tsttcs01 4-10 BROK : Remaining cases broken
tsttcs01 0 WARN : cleanup(): kill(0, SIGALRM) failed; errno = 3: No such process
SEE ALSO
utst_res(1), tst_setup(1), printf(3C), ksh(1).
DIAGNOSTICS
A WARN result message will be printed if any of the following occur:
If an invalid test type is specified.
If Tst_count is negative.
If Tst_range is non-positive.
If Tst_range is > 1, and the test type is TINFO or TWARN.
If one of the tst_brk[loop][m]() routines is called with a test
type other than TFAIL, TBROK, TCONF, or TRETR.
If Tst_lpstart is negative.
If Tst_lptotal is non-positive.
If there are any problems opening/reading/writing the contents of
fname.
LIMITATIONS
If fname is NULL and tmesg is NULL or empty, the result message will be
empty. This allows a test to not print a message for a result, but it
is not advised.
BUGS
The programmer is free to alter the value of Tst_count causing possible
test result order problems.