epicsUnitTest.h
Unit test routines.
The unit test routines make it easy for a test program to generate output that is compatible with the Test Anything Protocol and can thus be used with Perl’s automated Test::Harness as well as generating human-readable output. The routines detect whether they are being run automatically and print a summary of the results at the end if not.
- Author
Andrew Johnson
A test program starts with a call to testPlan(), announcing how many tests are to be conducted. If this number is not known a value of zero can be used during development, but it is recommended that the correct value be substituted after the test program has been completed.
Individual test results are reported using any of testOk(), testOk1(), testOkV(), testPass() or testFail(). The testOk() call takes and also returns a logical pass/fail result (zero means failure, any other value is success) and a printf-like format string and arguments which describe the test. The convenience macro testOk1() is provided which stringifies its single condition argument, reducing the effort needed when writing test programs. The individual testPass() and testFail() routines can be used when the test program takes a different path on success than on failure, but one or other must always be called for any particular test. The testOkV() routine is a varargs form of testOk() included for internal purposes which may prove useful in some cases.
If some program condition or failure makes it impossible to run some tests, the testSkip() routine can be used to indicate how many tests are being omitted from the run, thus keeping the test counts correct; the constant string why is displayed as an explanation to the user (this string is not printf-like).
If some tests are expected to fail because functionality in the module under test has not yet been fully implemented, these tests may still be executed, wrapped between calls to testTodoBegin() and testTodoEnd(). testTodoBegin() takes a constant string indicating why these tests are not expected to succeed. This modifies the counting of the results so the wrapped tests will not be recorded as failures.
Additional information can be supplied using the testDiag() routine, which displays the relevant information as a comment in the result output. None of the printable strings passed to any testXxx() routine should contain a newline ‘\n’ character, newlines will be added by the test routines as part of the Test Anything Protocol. For multiple lines of diagnostic output, call testDiag() as many times as necessary.
If at any time the test program is unable to continue for some catastrophic reason, calling testAbort() with an appropriate message will ensure that the test harness understands this. testAbort() does not return, but calls the ANSI C routine abort() to cause the program to stop immediately.
After all of the tests have been completed, the return value from testDone() can be used as the return status code from the program’s main() routine.
On vxWorks and RTEMS, an alternative test harness can be used to run a series of tests in order and summarize the results from them all at the end just like the Perl harness does. The routine testHarness() is called once at the beginning of the test harness program. Each test program is run by passing its main routine name to the runTest() macro which expands into a call to the runTestFunc() routine. The last test program or the harness program itself must finish by calling testHarnessDone() which triggers the summary mechanism to generate its result outputs (from an epicsAtExit() callback routine).
Announcing Test Results
Routines that declare individual test results.
-
testOk1(cond)
Test result using expression as description.
- Parameters:
cond – Expression to be evaluated and displayed.
- Returns:
The value of
cond.
-
int testOk(int pass, const char *fmt, ...)
Test result with printf-style description.
- Parameters:
pass – True/False value indicating result.
fmt – A printf-style format string describing the test.
... – Any parameters required for the format string.
- Returns:
The value of
pass.
-
int testOkV(int pass, const char *fmt, va_list pvar)
Test result with var-args description.
- Parameters:
pass – True/False value indicating result.
fmt – A printf-style format string describing the test.
pvar – A var-args pointer to any parameters for the format string.
- Returns:
The value of
pass.
-
void testPass(const char *fmt, ...)
Passing test result with printf-style description.
- Parameters:
fmt – A printf-style format string describing the test.
... – Any parameters required for the format string.
-
void testFail(const char *fmt, ...)
Failing test result with printf-style description.
- Parameters:
fmt – A printf-style format string describing the test.
... – Any parameters required for the format string.
Test Harness for Embedded OSs
These routines are used to create a test-harness that can run multiple test programs, collect their names and results, then display a summary at the end of testing.
-
runTest(func)
Run a test program.
- Parameters:
func – Name of the test program.
-
testHarnessDone()
Declare all test programs finished.
-
typedef int (*TESTFUNC)(void)
-
void testHarness(void)
Initialize test harness.
-
void testHarnessExit(void *dummy)
End of testing.
Missing or Failing Tests
Routines for handling special situations.
-
void testSkip(int skip, const char *why)
Place-holders for tests that can’t be run.
- Parameters:
skip – How many tests are being skipped.
why – Reason for skipping these tests.
-
void testTodoBegin(const char *why)
Mark the start of a group of tests that are expected to fail.
- Parameters:
why – Reason for expected failures.
-
void testTodoEnd(void)
Mark the end of a failing test group.
-
void testAbort(const char *fmt, ...)
Stop testing, program cannot continue.
- Parameters:
fmt – A printf-style format string giving the reason for stopping.
... – Any parameters required for the format string.
Functions
-
void testPlan(int tests)
Declare the test plan, required.
- Parameters:
tests – Number of tests to be run. May be zero if not known but the test harness then can’t tell if the program dies prematurely.
-
int testDiag(const char *fmt, ...)
Output additional diagnostics.
- Parameters:
fmt – A printf-style format string containing diagnostic information.
... – Any parameters required for the format string.
-
int testDone(void)
Mark the end of testing.
-
int testImpreciseTiming(void)
Return non-zero in shared/oversubscribed testing environments.
May be used to testSkip(), or select longer timeouts, for some cases when the test process may be preempted for arbitrarily long times. This is common in shared CI environments.
The environment variable $EPICS_TEST_IMPRECISE_TIMING=YES should be set in by such testing environments.