test/README

   1
   2 Unit test
   3
   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).
   9
  10 To run the tests:
  11         ksh unit_test.sh [specific-test]
  12
  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.
  16
  17 Output is an interpretation of the resulting gcov output (in more useful
  18 and/or easier to read format).  For example:
  19
  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
  25 [LOW]   76% uta_mk_ring
  26 [PASS]  91% ../src/common/src/ring_static.c
  27
  28
  29 The output shows, for each function, the coverage (column 2) and an
  30 interpretation (ok or low) wthin an overall pass or fail.
  31
  32
  33 File Names
  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.
  41
  42
  43 Discounting
  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 (###).
  53
  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
  56 the -f option.
  57
  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:
  62
  63      -:  354:
  64      1:  355:    dbuf = strdup( buf );
  65      1:  356:    if( dbuf == NULL  ) {
  66  =====:  357:        errno = ENOMEM;
  67  =====:  358:        return 0;
  68      -:  359:    }
  69
  70
  71 Target Coverage
  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.
  76
  77
  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.