[master] ATF usage and documentation cleaned up

    Merges in rt38619

3 files changed, 121 insertions, 13 deletions

diff --git a/tests/HOWTO-unit-test b/tests/HOWTO-unit-test
index b84beba3..e00b7d58 100644
--- a/tests/HOWTO-unit-test
+++ b/tests/HOWTO-unit-test
@@ -13,7 +13,7 @@ and then opening doc/html/index.html
 Tests Overview
 --------------
 
-In DHCP, a unit test exercises a particular piece of code in 
+In DHCP, a unit test exercises a particular piece of code in
 isolation. There is a separate unit test per module or API. Each unit
 test lives in a directory beneath the code it is designed to exercise.
 So, we (will eventually) have:
@@ -26,31 +26,57 @@ So, we (will eventually) have:
 And so on.
 
 We are using ATF (Automated Test Framework) as a framework to run our
-unittests. See ISC DHCP Developer's Guide for much more thorough
+unit tests. See ISC DHCP Developer's Guide for much more thorough
 description of unit-test and ATF framework in general.
 
+Installing ATF
+--------------
+ATF sources can be downloaded from https://github.com/jmmv/kyua. ATF
+must be configured, compiled and then installed to be available during
+the DHCP configure procedure. Please follow INSTALL file supplied with
+ATF sources (it's essentially the typical ./configure && make &&
+make install procedure).
+
+Beginning with ATF version 0.16, it is necessary to include the following
+options --enable-tools and --disable-shared when configuring ATF:
+
+    configure --prefix=<prefix> --enable-tools --disable-shared
+
+ISC DHCP unittests will run with ATF releases upto 0.19.  Beginning with
+ATF 0.20, the tools, atf-run and atf-report required by ISC DHCP, were
+deprecated and are no longer included with ATF.
+
 Running Unit Tests
 ------------------
 
 In order to run the unit tests for DHCP, enable ATF support during configure:
 
-$ ./configure --with-atf
+$ ./configure --with-atf{=<atf-path>}
+
+    where <atf-path> is the path into which ATF was installed.  This would
+    be same value used for --prefix when ATF was configured (default is
+    /usr/local).
 
-And then use:
+And then build ISC_DHCP with:
+
+$ make
+
+Finally build and run unit tests with:
 
 $ make check
 
-This will run all of the unit tests. Make sure that ATF is actually
-installed and that you have atf-run and atf-report tool in your PATH.
+This will traverse the source tree running the unit tests in each unit test
+subdirectory.  Note that if one or more tests in a unit test subdirectory fail
+the make process will stop.  To run all of the tests regardless of outcome,
+use:
+
+$ make -k check
 
-You can run a single test by going to the appropriate test directory 
+You can run a single test by going to the appropriate test directory
 and invoking the test directly:
 
 $ cd server/tests
-$ atf-run | atf-report
-
-There are also a number of options that you can use when running a
-test. See atf-run and atf-report documentation.
+$ make check
 
 Adding a New Unit Test
 ----------------------
diff --git a/tests/Makefile.in b/tests/Makefile.in
index 79477b7b..629339d7 100644
--- a/tests/Makefile.in
+++ b/tests/Makefile.in
@@ -79,14 +79,14 @@ build_triplet = @build@
 host_triplet = @host@
 subdir = tests
 DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
-	$(top_srcdir)/depcomp
+	$(srcdir)/unittest.sh.in $(top_srcdir)/depcomp
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
 	$(ACLOCAL_M4)
 mkinstalldirs = $(install_sh) -d
 CONFIG_HEADER = $(top_builddir)/includes/config.h
-CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_FILES = unittest.sh
 CONFIG_CLEAN_VPATH_FILES =
 AR = ar
 ARFLAGS = cru
@@ -156,6 +156,7 @@ DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
 ACLOCAL = @ACLOCAL@
 AMTAR = @AMTAR@
 AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+ATF_BIN = @ATF_BIN@
 ATF_CFLAGS = @ATF_CFLAGS@
 ATF_LDFLAGS = @ATF_LDFLAGS@
 AUTOCONF = @AUTOCONF@
@@ -320,6 +321,8 @@ $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
 $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
 	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
 $(am__aclocal_m4_deps):
+unittest.sh: $(top_builddir)/config.status $(srcdir)/unittest.sh.in
+	cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
 
 clean-checkLIBRARIES:
 	-test -z "$(check_LIBRARIES)" || rm -f $(check_LIBRARIES)
diff --git a/tests/unittest.sh.in b/tests/unittest.sh.in
new file mode 100755
index 00000000..0ee7ab70
--- /dev/null
+++ b/tests/unittest.sh.in
@@ -0,0 +1,79 @@
+#!/bin/sh
+#
+# Copyright (C) 2015  Internet Systems Consortium, Inc. ("ISC")
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+# PERFORMANCE OF THIS SOFTWARE.
+#
+# Script used to execute unit tests described by the Atffile in the current
+# directory.  It exits with return value of atf-run, which will be 0 if all
+# tests passed, non-zero otherwise.
+#
+
+# Add configured path to ATF tools, atf-run and atf-report
+PATH="@ATF_BIN@:${PATH}"
+export PATH
+
+# colors if not outputting to a dumb terminal and stdout is a tty
+if test "$TERM" != dumb && { test -t 1; } 2>/dev/null; then \
+    red='\033[0;31m'
+    green='\033[0;32m'
+    noclr='\033[0m'
+
+    # if echo supports -e, we must use it to set colors
+    # (output will be "" if its supported)
+    if [ -z "`echo -e`" ]
+    then
+        dash_e="-e"
+    fi
+fi;
+
+header="===================================================="
+
+status=0
+if [ -n "@ATF_BIN@" -a -f Atffile ]
+then
+    # run the tests
+    echo "Running unit tests..."
+	atf-run > atf.out
+	status=$?
+
+    # set color based on success/failure
+	if [ $status -eq 0 ]
+	then
+        color=$green
+	else
+        color=$red
+	fi
+
+    # spit out the test report
+    # We print everything upto the summary in
+    # "no color".  Print the summary in our
+    # result color.
+    cat atf.out | atf-report | while read line
+    do
+        cnt=`echo $line | grep -c "Summary"`
+        if [ $cnt -eq 1 ]
+        then
+            echo $dash_e $color$header
+        fi
+        echo $line;
+    done
+    echo $dash_e $header$noclr
+
+    # clean up unless there were test failures
+    if [ $status -eq 0 ]
+    then
+        rm -f atf.out
+    fi
+fi
+exit $status