Experimental Physics and
Industrial Control System

Andrew Johnson <[email protected]> · Fri, 8 Dec 2017 12:32:48 -0600

Hi Dirk,

Sorry for the delay, I seemingly spent all day yesterday tracking down
Travis-CI build issues. I'm responding now for other developers too…

On 12/07/2017 08:43 AM, Dirk Zimoch wrote:
> Is there any documentation how to write EPICS unit tests?

Section 19.18.12 of the AppDevGuide at

>   http://www.aps.anl.gov/epics/base/R3-16/1-docs/AppDevGuide/libCom.html#x20-80900019.18.12

covers the epicsUnitTest.h API but copying existing examples is also
good (and necessary for Michael's additional dbUnitTest.h routines,
although he does provide useful comments in that header file).

The overall design and the output of the epicsUnitTest.h functions
follows Perl's Test::More module (run 'perldoc Test::More' for the
man-page) so it's worth understanding that philosophy. In our case most
of the final-argument strings that Perl calls $test_name take printf
format strings with varargs to follow.

In some existing test programs the testOk1() macro gets used rather more
than I would like it to be; it just stringifies its one argument to
generate the test name. In some cases (like epicsCalcTest.cpp and
epicsMathTest) the expression being tested is a good representation of
the check being performed, but in other places that expression gives no
hint as to what was actually being checked, e.g.:

> epicsMessageQueueTest.cpp:    testOk1(errors == 0);

Note that testOk() and testOk1() return the value of their int pass
argument, so tests can display additional information about failures
using this construct:

>     if ( ! testOk1 ( cancelVerify::cancelCount == 0 ) )
>         testDiag ( "cancelCount = %u", cancelVerify::cancelCount );

Don't put "\n" newlines in your test names or diagnostic strings, they
get added automatically.

Please try to ensure that your test programs always run exactly the same
number of tests, even when some of them fail (unless the program calls
testAbort() because it found something that stops it from continuing).
In general I won't accept code that calls testPlan(0), please remember
to replace the zero with the actual number of tests before requesting a
merge. If the test isn't sure in advance how many iterations of a loop
will occur, have the code count the iterations and make the test result
be that the count was correct after the loop finishes, don't just call
testOk()/testPass()/testFail() inside the loop.

Also be aware that different systems will run tests at different speeds
(some of our CI systems are CPU-starved), so never rely on relative
timing between threads but explicitly add mutexes and/or semaphores to
wait for other threads to finish doing work.

HTH, and thanks!

- Andrew

-- 
Arguing for surveillance because you have nothing to hide is no
different than making the claim, "I don't care about freedom of
speech because I have nothing to say." -- Edward Snowdon

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System