test(unit): Extend unit tests

[ric-plt/lib/rmr.git] / test / README

diff --git a/test/README b/test/README
index 85f96ed..5adc3f8 100644 (file)
--- a/test/README
+++ b/test/README
@@ -1,21 +1,25 @@
 
 Unit test
 
 
 Unit test
 

-The means to unit testing the RMr library is contained in
-this directory.  It is somewhat difficult to accurately generate
-coverage information for parts of the library because the library
-is a fair amount of static functions (to keep them from being
-visible to the user programme).  
+This directory contains the unit test support for the RMr
+library.  The basic test is run with the follwing command:

 
 

-To run the tests:
-       ksh unit_test.sh [specific-test]
+       ksh unit_test.ksh

 
 

-If a specific test (e.g. ring_test.c) is not given on the command line,
-all *_test.c files are sussed out and an attempt to build and run them
-is made by the script. 
+To run a specific test (e.g. ring_test.c) run:
+       ksh unit_test.ksh ring_test.c

 
 

-Output is an interpretation of the resulting gcov output (in more useful
-and/or easier to read format).  For example:
+The script runs the unit test(s) given, and if they pass then
+runs an analysis on the .gcov files generated to generate
+coverage information.  By default, pass/fail of the test is
+based only on the success or failure of the unit tests which
+are testing functionality.  The unit test script can report
+an overall failure if coverage is below the indicated threshold
+when given the strict option (-s).
+
+The analysis of .gcov files generates output shown below which
+is thought to be more straight forward than the typical stuff
+gcov produces:

 
 unit_test.ksh ring_test.c
 ring_test.c --------------------------------------
 
 unit_test.ksh ring_test.c
 ring_test.c --------------------------------------


@@ -26,18 +30,29 @@ ring_test.c --------------------------------------
 [PASS]  91% ../src/common/src/ring_static.c
 
 
 [PASS]  91% ../src/common/src/ring_static.c
 
 

-The output shows, for each function, the coverage (column 2) and an 
+The output shows, for each function, the coverage (column 2) and an

 interpretation (ok or low) wthin an overall pass or fail.
 
 
 interpretation (ok or low) wthin an overall pass or fail.
 
 

-File Names
-The unit test script will find all files named *_test.c and assume that
-they can be compiled and executed using the local Makefile. Files
-which are needed by these programmes (e.g. common functions) are expected
-to reside in this directory as test_*.c and test_*.h files and should 
-be directly included by the test programmes (not built and linked). This 
-allows the unit test script to isngore the functions, and files, when 
-generating coverage reports. 
+Because of the static nature of the RMr library, tests with the
+intent of providing coverage information, as opposed just to providing
+functional verification, are a bit trickier.  To that end, the test
+files in this directory are organised with three file name formats:
+
+       test_*.c  tools for testing, not tests
+
+       *_test.c  main test programmes which can be compiled in
+                         a stand-alone manner (e.g. gcc foo_test.c)
+
+       *_static_test.c  Test functions which are real tests and are
+                         included by one or more stand-alone driver.
+
+The unit_test script will search only for *_test.c and will ignore
+*_static_test.c files when building it's list for testing.
+
+
+Use the command 'unit_test.ksh -?' to see the usage information
+and complete set of options available.

 
 
 Discounting
 
 
 Discounting


@@ -51,13 +66,13 @@ option is given, an augmented coverage listing is saved in .dcov which
 shows the discounted lines with a string of equal signs (====) rather
 than the gcov hash string (###).
 
 shows the discounted lines with a string of equal signs (====) rather
 than the gcov hash string (###).
 

-The discount check is applied only if an entire module has a lower 
-than accepted coverage rate, and can be forced for all modules with 
+The discount check is applied only if an entire module has a lower
+than accepted coverage rate, and can be forced for all modules with

 the -f option.
 
 To illustrate, the following code checks the return from the system
 library strdup() call which is very unlikely to fail under test without
 the -f option.
 
 To illustrate, the following code checks the return from the system
 library strdup() call which is very unlikely to fail under test without

-going to extremes and substituting for the system lib.  Thus, the 
+going to extremes and substituting for the system lib.  Thus, the

 block which checks for a nil pointer has been discounted:
 
      -:  354:
 block which checks for a nil pointer has been discounted:
 
      -:  354:


@@ -70,13 +85,13 @@ block which checks for a nil pointer has been discounted:
 
 Target Coverage
 By default, a target coverage of 80% is used. For some modules this may
 
 Target Coverage
 By default, a target coverage of 80% is used. For some modules this may

-be impossible to achieve, so to prevent always failing these modules 
+be impossible to achieve, so to prevent always failing these modules

 may be listed in the .targets file with their expected minimum coverage.
 Module names need to be qualified (e.g. ../src/common/src/foo.c.
 
 
 -----------------------------------------------------------------------
 A note about ksh (A.K.A Korn shell, or kshell)
 may be listed in the .targets file with their expected minimum coverage.
 Module names need to be qualified (e.g. ../src/common/src/foo.c.
 
 
 -----------------------------------------------------------------------
 A note about ksh (A.K.A Korn shell, or kshell)

-Ksh is preferred for more complex scripts such as the unit test 
+Ksh is preferred for more complex scripts such as the unit test

 script as it does not have some of the limitations that bash
 script as it does not have some of the limitations that bash

-(and other knock-offs) have. 
+(and other knock-offs) have.