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.