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 Discounting
  59 The unit test script makes a discount pass on low coverage files in
  60 attempt to discount the coverage rate by ignoring what are considered
  61 to be difficult to reach blocks in the code.  Currently, these blocks
  62 are limited to what appear to be tests for memory allocation, failure
  63 and/or nil pointer handling.  If code blocks of this sort are found,
  64 they are not counted against the coverage for the module.  If the -v
  65 option is given, an augmented coverage listing is saved in .dcov which
  66 shows the discounted lines with a string of equal signs (====) rather
  67 than the gcov hash string (###).
  68
  69 The discount check is applied only if an entire module has a lower
  70 than accepted coverage rate, and can be forced for all modules with
  71 the -f option.
  72
  73 To illustrate, the following code checks the return from the system
  74 library strdup() call which is very unlikely to fail under test without
  75 going to extremes and substituting for the system lib.  Thus, the
  76 block which checks for a nil pointer has been discounted:
  77
  78      -:  354:
  79      1:  355:    dbuf = strdup( buf );
  80      1:  356:    if( dbuf == NULL  ) {
  81  =====:  357:        errno = ENOMEM;
  82  =====:  358:        return 0;
  83      -:  359:    }
  84
  85
  86 Target Coverage
  87 By default, a target coverage of 80% is used. For some modules this may
  88 be impossible to achieve, so to prevent always failing these modules
  89 may be listed in the .targets file with their expected minimum coverage.
  90 Module names need to be qualified (e.g. ../src/common/src/foo.c.
  91
  92
  93 -----------------------------------------------------------------------
  94 A note about ksh (A.K.A Korn shell, or kshell)
  95 Ksh is preferred for more complex scripts such as the unit test
  96 script as it does not have some of the limitations that bash
  97 (and other knock-offs) have.