4 The means to unit testing the RMr library is contained in
5 this directory. It is somewhat difficult to accurately generate
6 coverage information for parts of the library because the library
7 is a fair amount of static functions (to keep them from being
8 visible to the user programme).
11 ksh unit_test.sh [specific-test]
13 If a specific test (e.g. ring_test.c) is not given on the command line,
14 all *_test.c files are sussed out and an attempt to build and run them
15 is made by the script.
17 Output is an interpretation of the resulting gcov output (in more useful
18 and/or easier to read format). For example:
20 unit_test.ksh ring_test.c
21 ring_test.c --------------------------------------
22 [OK] 100% uta_ring_insert
23 [OK] 100% uta_ring_extract
24 [OK] 100% uta_ring_free
26 [PASS] 91% ../src/common/src/ring_static.c
29 The output shows, for each function, the coverage (column 2) and an
30 interpretation (ok or low) wthin an overall pass or fail.
34 The unit test script will find all files named *_test.c and assume that
35 they can be compiled and executed using the local Makefile. Files
36 which are needed by these programmes (e.g. common functions) are expected
37 to reside in this directory as test_*.c and test_*.h files and should
38 be directly included by the test programmes (not built and linked). This
39 allows the unit test script to isngore the functions, and files, when
40 generating coverage reports.
44 The unit test script makes a discount pass on low coverage files in
45 attempt to discount the coverage rate by ignoring what are considered
46 to be difficult to reach blocks in the code. Currently, these blocks
47 are limited to what appear to be tests for memory allocation, failure
48 and/or nil pointer handling. If code blocks of this sort are found,
49 they are not counted against the coverage for the module. If the -v
50 option is given, an augmented coverage listing is saved in .dcov which
51 shows the discounted lines with a string of equal signs (====) rather
52 than the gcov hash string (###).
54 The discount check is applied only if an entire module has a lower
55 than accepted coverage rate, and can be forced for all modules with
58 To illustrate, the following code checks the return from the system
59 library strdup() call which is very unlikely to fail under test without
60 going to extremes and substituting for the system lib. Thus, the
61 block which checks for a nil pointer has been discounted:
64 1: 355: dbuf = strdup( buf );
65 1: 356: if( dbuf == NULL ) {
66 =====: 357: errno = ENOMEM;
72 By default, a target coverage of 80% is used. For some modules this may
73 be impossible to achieve, so to prevent always failing these modules
74 may be listed in the .targets file with their expected minimum coverage.
75 Module names need to be qualified (e.g. ../src/common/src/foo.c.
78 -----------------------------------------------------------------------
79 A note about ksh (A.K.A Korn shell, or kshell)
80 Ksh is preferred for more complex scripts such as the unit test
81 script as it does not have some of the limitations that bash
82 (and other knock-offs) have.