enhance(API): Add constant passthru for wrappers
[ric-plt/lib/rmr.git] / test / README
1
2 Unit test
3
4 This directory contains the unit test support for the RMr
5 library.  The basic test is run with the follwing command:
6
7         ksh unit_test.ksh
8
9 To run a specific test (e.g. ring_test.c) run:
10         ksh unit_test.ksh ring_test.c
11
12 The script runs the unit test(s) given, and if they pass then
13 runs an analysis on the .gcov files generated to generate
14 coverage information.  By default, pass/fail of the test is
15 based only on the success or failure of the unit tests which
16 are testing functionality.  The unit test script can report
17 an overall failure if coverage is below the indicated threshold
18 when given the strict option (-s).
19
20 The analysis of .gcov files generates output shown below which
21 is thought to be more straight forward than the typical stuff
22 gcov produces:
23
24 unit_test.ksh ring_test.c
25 ring_test.c --------------------------------------
26 [OK]   100% uta_ring_insert
27 [OK]   100% uta_ring_extract
28 [OK]   100% uta_ring_free
29 [LOW]   76% uta_mk_ring
30 [PASS]  91% ../src/common/src/ring_static.c
31
32
33 The output shows, for each function, the coverage (column 2) and an
34 interpretation (ok or low) wthin an overall pass or fail.
35
36
37 Because of the static nature of the RMr library, tests with the
38 intent of providing coverage information, as opposed just to providing
39 functional verification, are a bit trickier.  To that end, the test
40 files in this directory are organised with three file name formats:
41
42         test_*.c  tools for testing, not tests
43
44         *_test.c  main test programmes which can be compiled in
45                           a stand-alone manner (e.g. gcc foo_test.c)
46
47         *_static_test.c  Test functions which are real tests and are
48                           included by one or more stand-alone driver.
49
50 The unit_test script will search only for *_test.c and will ignore
51 *_static_test.c files when building it's list for testing.
52
53
54 Use the command 'unit_test.ksh -?' to see the usage information
55 and complete set of options available.
56
57
58 Merging .gcov files
59 As some unit test programmes may not be able/designed to cover all 
60 of a module completely, the script will merge each .gcov prooduced
61 with the prior, matching, file after each pass.  The result is a
62 final .gcov file that shows the coverage of the module over all 
63 tests.  This allows a true coverage value to be determined while 
64 permitting more simple tests to be used without the requirement of
65 each test to cover everything.
66
67
68 Discounting
69 The unit test script makes a discount pass on low coverage files in
70 attempt to discount the coverage rate by ignoring what are considered
71 to be difficult to reach blocks in the code.  Currently, these blocks
72 are limited to what appear to be tests for memory allocation, failure
73 and/or nil pointer handling.  If code blocks of this sort are found,
74 they are not counted against the coverage for the module.  If the -v
75 option is given, an augmented coverage listing is saved in .dcov which
76 shows the discounted lines with a string of equal signs (====) rather
77 than the gcov hash string (###).
78
79 The discount check is applied only if an entire module has a lower
80 than accepted coverage rate, and can be forced for all modules with
81 the -f option.
82
83 To illustrate, the following code checks the return from the system
84 library strdup() call which is very unlikely to fail under test without
85 going to extremes and substituting for the system lib.  Thus, the
86 block which checks for a nil pointer has been discounted:
87
88      -:  354:
89      1:  355:    dbuf = strdup( buf );
90      1:  356:    if( dbuf == NULL  ) {
91  =====:  357:        errno = ENOMEM;
92  =====:  358:        return 0;
93      -:  359:    }
94
95 A final discount pass is made on all merged .gcov files after all unit 
96 tests are finished. This final pass should indicate the true discounted
97 coverage
98
99
100 Target Coverage
101 By default, a target coverage of 80% is used. For some modules this may
102 be impossible to achieve, so to prevent always failing these modules
103 may be listed in the .targets file with their expected minimum coverage.
104 Module names need to be qualified (e.g. ../src/common/src/foo.c.
105
106
107 Sonar XML Files
108 If the -x option is given on the unit test script, then two XML files 
109 will be generated for Sonar.  These are gcov.xml and dcov.xml and are 
110 the coverage information as reflected in the merged .gcov files and in
111 the .dcov files produced during the final pass.   The XML files should
112 be uploaded to Sonar only after a complete unit test run is made, otherwise
113 the coverage information may be lacking (reflecting only the last test
114 executed and not a full complement of tests).
115
116 -----------------------------------------------------------------------
117 A note about ksh (A.K.A Korn shell, or kshell)
118 Ksh is preferred for more complex scripts such as the unit test
119 script as it does not have some of the limitations that bash
120 (and other knock-offs) have.