Additional documentation for test scripts

Added documentation in comments in test scripts, added example site.sh,
moved evaluation of site.sh later in lib.sh to allow site.sh to override
more lib.sh variables.

.gitignore

@@ -51,10 +51,15 @@ build-root/*.rpm
 build-root/rpmbuild
 
 util/clixon_util_datastore
-util/clixon_util_insert
+util/clixon_util_grpc
 util/clixon_util_json
+util/clixon_util_path
+util/clixon_util_regexp
+util/clixon_util_socket
+util/clixon_util_ssl
 util/clixon_util_stream
 util/clixon_util_xml
+util/clixon_util_xml_mod
 util/clixon_util_xpath
 util/clixon_util_yang
 
@@ -62,4 +67,4 @@ test/config.sh
 test/site.sh
 test/vagrant/site.mk
 test/cicd/site.mk
-doc/html
+doc/html

test/all.sh

@@ -1,13 +1,27 @@
 #!/usr/bin/env bash
-# Run, eg as:
+# Run test_*.sh tests, stop on error, verbose logging, no pass/fail summary.
-# ./all.sh 2>&1 | tee test.log # break on first test
+#
+# This script requires the user to be in the sudo group.
+#
+# The 'pattern' variable determines which test files to execute.
+# By default, run all the tests in the test_*.sh files in this directory.
 
-# Pattern to run tests, default is all, but you may want to narrow it down
 : ${pattern:=test_*.sh}
 
+# You can specify tests files to exclude using the 'SKIPLIST' variable in a
+# site.sh file. See example in README.md. Files excluded by the 'SKIPLIST'
+# variable have precedence over files included by the 'pattern' variable.
+
+# This script does not take arguments, so if arguments exist, print the Usage
+# in http://docopt.org/ format.
 if [ $# -gt 0 ]; then 
-    echo "usage: $0 # detailed logs and stop on first error. Use pattern=\"\" $0 to"
+    echo "Usage:"
-    echo "     Use pattern=<pattern> $0 to narrow down test cases"
+    echo "    $0                               # Run all 'test_*.sh' files"
+    echo "    pattern=<Bash glob pattern> $0   # Run only files matching the pattern"
+    echo ""
+    echo "Example:"
+    echo "    ${0} 2>&1 | tee test.log         # Run all tests, output to 'test.log'"
+    echo "    pattern=test_feature.sh ${0}     # Run only the tests in 'test_feature.sh'"
     exit -1
 fi
 

test/lib.sh

@@ -1,5 +1,9 @@
 #!/usr/bin/env bash
 # Define test functions.
+# See numerous configuration variables later on in this file that you can set
+# in the environment or the site.sh file. The definitions in the site.sh file 
+# override 
+#
 # Create working dir as variable "dir"
 # The functions are somewhat wildgrown, a little too many:
 # - expectfn
@@ -17,8 +21,11 @@
 # Testfile (not including path)
 : ${testfile:=$(basename $0)}
 
-# Add test to this list that you dont want run
+# SKIPLIST lists the filenames of the test files that you do *not* want to run.
-# Typically add them in your site file
+# The format is a whitespace separated list of filenames. Specify the SKIPLIST
+# either in the shell environment or in the site.sh file. Any SKIPLIST specified
+# in site.sh overrides a SKIPLIST specified in the environment. If not specified
+# in either the environment or the site.sh, then the default SKIPLIST is empty.
 : ${SKIPLIST:=""}
 
 # Some tests (openconfig/yang_models) just test for the cli to return a version
@@ -34,21 +41,6 @@ if [ -f ./config.sh ]; then
     fi
 fi
 
-# Site file, an example of this file in README.md
-if [ -f ./site.sh ]; then
-    . ./site.sh
-    if [ $? -ne 0 ]; then
-	return -1 # skip
-    fi
-    # test skiplist.
-    for f in $SKIPLIST; do
-	if [ "$testfile" = "$f" ]; then
-	    echo "...skipped (see site.sh)"
-	    return -1 # skip
-	fi
-    done
-fi
-
 # Test number from start
 : ${testnr:=0}
 
@@ -122,7 +114,6 @@ fi
 
 # Standard IETF RFC yang files. 
 : ${IETFRFC=../yang/standard}
-#: ${IETFRFC=$YANGMODELS/standard/ietf/RFC}
 
 # Backend user
 BUSER=clicon
@@ -141,6 +132,23 @@ BUSER=clicon
 
 : ${clixon_backend:=clixon_backend}
 
+# Source the site-specific definitions for test script variables, if site.sh
+# exists. The variables defined in site.sh override any variables of the same
+# names in the environment in the current execution.
+if [ -f ./site.sh ]; then
+    . ./site.sh
+    if [ $? -ne 0 ]; then
+	return -1 # skip
+    fi
+    # test skiplist.
+    for f in $SKIPLIST; do
+	if [ "$testfile" = "$f" ]; then
+	    echo "...skipped (see site.sh)"
+	    return -1 # skip
+	fi
+    done
+fi
+
 dir=/var/tmp/$0
 if [ ! -d $dir ]; then
     mkdir $dir

test/site.sh

@@ -0,0 +1,22 @@
+#!#/bin/sh
+# Use this file to specify local site-specific env variables, or tests to
+# skip. This file is sourced by lib.sh
+#
+# Add test filenames that you do not want to run to the SKIPLIST variable. The
+# SKIPLIST is evaluated as a Bash glob in lib.sh, so you can use it to skip
+# files from the begining of the file list up to a pattern by specifying an
+# appropriate glob such as "test_[a-n]*\.sh".
+#
+# The SKIPLIST has precedence over the 'pattern' variable that you can use to
+# specify included file when running the various test scripts such as "all.sh".
+#SKIPLIST="test_[a-t]*\.sh test_openconfig.sh test_yangmodels.sh"
+#
+# Parse yang openconfig models from https://github.com/openconfig/public
+#OPENCONFIG=/usr/local/share/openconfig/public
+#
+# Parse yangmodels from https://github.com/YangModels/yang
+#YANGMODELS=/usr/local/share/yangmodels
+#
+# Specify alternative directory for the standard IETF RFC yang files. 
+#IETFRFC=$YANGMODELS/standard/ietf/RFC
+

test/sum.sh

@@ -1,15 +1,30 @@
 #!/usr/bin/env bash
-# Run, eg as:
+# Run test_*.sh tests, continue on error, no logging, print pass/fail summary.
-# ./sum.sh # to run all tests and print 
+#
+# This script requires the user to be in the sudo group.
+#
+# The 'pattern' variable determines which test files are executed.
+# By default, run all the tests in the test_*.sh files in this directory.
 
+: ${pattern:=test_*.sh}
+
+# You can specify tests files to exclude using the 'SKIPLIST' variable in a
+# site.sh file. See example in README.md. Files excluded by the 'SKIPLIST'
+# variable have precedence over files included by the 'pattern' variable.
+
+# This script does not take arguments, so if arguments exist, print the Usage
+# in http://docopt.org/ format.
 if [ $# -gt 0 ]; then 
-    echo "usage: $0 # pipe to dev/null and continue on error"
+    echo "Usage:"
+    echo "    ${0}                             # Run all 'test_*.sh' files"
+    echo "    pattern=<Bash glob pattern> ${0} # Run only files matching the pattern"
+    echo ""
+    echo "Example:"
+    echo "    ${0} 2>&1 | tee test.log         # Run all tests, output to 'test.log'"
+    echo "    pattern=test_feature.sh ${0}     # Run only the tests in 'test_feature.sh'"
     exit -1
 fi
 
-# Pattern to run tests, default is all, but you may want to narrow it down
-: ${pattern:=test_*.sh}
-
 err=0
 for testfile in $pattern; do # For lib.sh the variable must be called testfile
     echo "Running $testfile"