initial version of kamailio unit tests framework

README.md

@@ -1,2 +1,129 @@
-# kamailio-tests
-Test Units For Kamailio SIP Server
+# Test Units For Kamailio SIP Server #
+
+Test framework with a set of unit tests for Kamailio SIP Server. It targets the use
+within a Docker container.
+
+Read more about Kamailio at:
+
+  * https://www.kamailio.org
+
+## The Test Framework ##
+
+The tests can be run using the command line tool `ktestsctl`. Run it without any parameter
+in order to see available options.
+
+A unit test is stored in its own directory inside the subfolder `units/`. The name of the
+directory is considered to be the name of the unit.
+
+The name of a unit test has the format `txxxxxnnnn`, the rules being:
+
+  * `t` - the first character in the name (`t` from `test`)
+  * `xxxx` - any five characters (use lower case letters) that should identify a group of tests
+  (e.g., `cfgxx` is used to identify tests related to default `kamailio.cfg`)
+  * `nnnn` - four digits to assign to different unit tests in the same group, use zeros to pad
+  in order to have always four digits (e.g., `0001`)
+
+Example of full unit test name: `tcfgxx0001`.
+
+Inside each unit directory should be at least two files:
+
+  * `unitname.sh` - an executable shell script to be used to run the unit (e.g., `tcfgxx0001.sh`)
+  * `README.md` - to contain the description for the unit test
+
+The shell script is executed inside the unit directory by `ktestsctl`.
+
+The `README.md` in a text file in `markdown` format. It should have a line that starts with
+`Summary: ` and provides a short description of the unit test. The text in the line after
+`Summary: ` is used by `ktestsctl` when writing the unit tests execution report.
+
+The framework has a configuration file located at `etc/config`. This is a shell script expected
+to have lines with `VARIABLE=value`, allowing to set paths to the applications used by
+unit scripts.
+
+Useful shell functions that might be handy to use in units are stored inside files from
+`lib` subfolder, like:
+
+  * `lib/utils` - common utility functions
+
+The Docker files that can be used to build Docker images to run the unit tests are located in
+`docker` subfolder. These are:
+
+  * `docker/Dockerfile` - container build with Debian 9.x (Stretch) deploying Kamailio installed
+  from source code. The directory with Kamailio source code is copied from local disk into the
+  container
+
+## Running Unit Tests ##
+
+### Dependencies ###
+
+  * `docker` - it has to be installed in order to follow the next instructions
+
+### Installation ###
+
+  * create a directory where to store the resources and go to it
+
+```
+mkdir kamailio-testing
+cd kamailio-testing
+```
+
+  * clone the `kamailio-tests` git repository
+
+```
+git clone https://github.com/kamailio/kamailio-tests
+```
+
+  * clone the `kamailio` git repository
+
+```
+git clone https://github.com/kamailio/kamailio
+```
+
+  * copy desired Dockerfile in the current folder
+
+```
+cp kamailio-tests/docker/Dockerfile
+```
+
+  * build the Docker image
+
+```
+docker build -t kamailio-tests-deb9x .
+```
+
+### Execute Unit Tests ###
+
+```
+docker run kamailio-tests-deb9x
+```
+
+With the default `Dockerfile`, the above command is running all unit tests.
+
+You can edit the `Dockerfile` and change the `CMD` line to execute a different command. Once
+you save the changes in the `Dockerfile`, rebuild the docker container and run.
+
+For example, run the unit tests in non-silent mode, set `CMD` inside `Dockerfile` to:
+
+```
+CMD /usr/local/src/kamailio-tests/ktestsctl run
+```
+
+Save and then run:
+
+```
+docker build -t kamailio-tests-deb9x .
+docker run kamailio-tests-deb9x
+```
+
+Example running only default `kamailio.cfg` related unit tests, update `Dockerfile` to have:
+
+```
+CMD /usr/local/src/kamailio-tests/ktestsctl run tcfgxx
+```
+
+Save and then run:
+
+```
+docker build -t kamailio-tests-deb9x .
+docker run kamailio-tests-deb9x
+```

docker/Dockerfile

@@ -0,0 +1,22 @@
+FROM debian:stretch
+
+RUN apt-get update
+RUN apt-get install --assume-yes apt-utils
+RUN apt-get install --assume-yes procps pkg-config gcc g++ make autoconf ctags
+RUN apt-get install --assume-yes bison flex libpcre3-dev libxml2-dev libssl-dev
+RUN apt-get install --assume-yes git ngrep vim
+RUN apt-get install --assume-yes sipsak sip-tester
+RUN DEBIAN_FRONTEND=noninteractive apt-get install --assume-yes mysql-client mysql-server default-libmysqlclient-dev
+
+COPY kamailio /usr/local/src/kamailio
+WORKDIR /usr/local/src/kamailio
+RUN make include_modules="db_mysql tls" cfg
+RUN make all
+RUN make install
+WORKDIR src/modules/tls
+RUN make install-tls-cert
+
+COPY kamailio-tests /usr/local/src/kamailio-tests
+WORKDIR /usr/local/src/kamailio-tests
+
+CMD /usr/local/src/kamailio-tests/ktestsctl -q run

etc/config

@@ -0,0 +1,10 @@
+# config variables
+
+KAMBIN=${KAMBIN:-/usr/local/sbin/kamailio}
+KAMCFG=${KAMCFG:-/usr/local/sbin/kamailio.cfg}
+KAMRUN=${KAMRUN:-/var/run/kamailio}
+KAMPID=${KAMPID:-${KAMRUN}/kamailio.pid}
+
+LOGFILE=/tmp/kamailio-tests.log
+
+UNITOUTPUT=${UNITOUTPUT:-yes}

ktestsctl

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+. etc/config
+
+### version for this script
+VERSION='1.0.0'
+LOGDATE=`date`
+
+ktestsctl_usage() {
+	cat <<EOF
+$0 [options] cmd [params]
+
+Options:
+  -q | --quiet ..... execution of unit tests in silent mode
+
+Commands:
+  -- command 'run' --
+  run .............. run all tests
+  run <filter> ..... run tests with a filter on unit names
+  run <unitname> ... run the test uning
+
+  -- command 'version' --
+  version .......... print the version string
+
+Version: $0 ${VERSION}
+
+EOF
+}
+
+ktestsrun() {
+	echo "=== unit tests execution start ==="
+	echo "running test units at: ${LOGDATE}" >${LOGFILE}
+	echo "" >>${LOGFILE}
+	if [ $# -lt 2 ] ; then
+		UNITSLIST=`find units/t* -maxdepth 1 -type d`
+	else
+		UNITSLIST=`find units/${1}* -maxdepth 1 -type d`
+	fi
+	for tdir in ${UNITSLIST} ; do
+		if [[ -d "${tdir}" && ! -L "${tdir}" ]]; then
+			tname=`basename ${tdir}`
+			texec="${tname}.sh"
+			tpath="${tdir}/${texec}"
+
+			if [[ -f "${tpath}" && -x "${tpath}" ]]; then
+				echo
+				tsummary=""
+				if [[ -f "${tdir}/README.md" ]]; then
+					tsummary=`grep "^Summary: " ${tdir}/README.md | cut -c10-`
+				fi
+				if [[ ! -z "${tsummary}" ]]; then
+					echo "* test unit ${tname}: ${tsummary}" | tee -a ${LOGFILE}
+				fi
+				echo "test unit ${tname}: running ..."
+				cd ${tdir}
+				if [ "${UNITOUTPUT}" == "no" ]; then
+					# save stdout and stderr, then redirect to /dev/null
+					exec 3>&1 4>&2 >/dev/null 2>&1
+				fi
+				./${texec}
+				ret=$?
+				if [ "${UNITOUTPUT}" == "no" ]; then
+					# restore stdout and stderr
+					exec 1>&3 2>&4
+				fi
+				cd ../..
+				if [ ! "$ret" -eq 0 ] ; then
+					echo "- test unit ${tname}: failed" | tee -a ${LOGFILE}
+				else
+					echo "- test unit ${tname}: ok" | tee -a ${LOGFILE}
+				fi
+			fi
+		fi
+	done
+	sleep 1
+	echo
+	echo "=== unit tests execution report ==="
+	echo
+	cat ${LOGFILE}
+	echo
+	echo "=== unit tests execution end ==="
+	echo
+}
+
+#
+##### ================================================ #####
+
+### evaluate first the options
+CMDPARAMS=()
+while [[ $# -gt 0 ]]
+do
+	key="$1"
+
+	case $key in
+		-q|--quiet)
+			UNITOUTPUT="no"
+			shift
+		;;
+		*)
+			CMDPARAMS+=("$1")
+			shift
+		;;
+	esac
+done
+
+set -- "${CMDPARAMS[@]}" # restore positional parameters
+
+### main command switch
+#
+case $1 in
+	run)
+		if [ $# -lt 2 ] ; then
+			ktestsrun
+		else
+			ktestsrun "${1}"
+		fi
+		;;
+	version)
+		echo  "$0 $VERSION"
+		;;
+
+	*)
+		ktestsctl_usage
+		exit 1
+		;;
+esac

libs/utils

@@ -0,0 +1,9 @@
+# common functions
+
+kill_kamailio() {
+	killall kamailio
+}
+
+kill_pidfile() {
+	kill $(cat ${1})
+}

units/tcfgxx0001/README.md

@@ -0,0 +1,9 @@
+# Default Config File - Basic Load Tests #
+
+Summary: default config file - basic load tests
+
+Following tests are done:
+
+  * run kamailio -c
+  * run kamailio with default config
+  * run kamailio with -A WITH_DEBUG

units/tcfgxx0001/tcfgxx0001.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+. ../../etc/config
+. ../../libs/utils
+
+# run default config check
+${KAMBIN} -c
+ret=$?
+if [ ! "$ret" -eq 0 ] ; then
+    exit $ret
+fi
+
+# start with default config
+${KAMBIN} -P ${KAMPID} -w ${KAMRUN} -Y ${KAMRUN} -a no
+ret=$?
+sleep 1
+kill_pidfile ${KAMPID}
+if [ ! "$ret" -eq 0 ] ; then
+    exit $ret
+fi
+
+# start with default config and -A WITH_DEBUG
+${KAMBIN} -P ${KAMPID} -w ${KAMRUN} -Y ${KAMRUN} -a no -A WITH_DEBUG
+ret=$?
+sleep 1
+kill_pidfile ${KAMPID}
+if [ ! "$ret" -eq 0 ] ; then
+    exit $ret
+fi
+
+exit $ret

units/tcfgxx0002/README.md

@@ -0,0 +1,7 @@
+# Default Config File - Basic SIP Signaling Tests #
+
+Summary: default config file - basic sip signaling tests
+
+Following tests are done:
+
+  * load with default config file and sent OPTIONS with sipsak to sip:127.0.0.1

units/tcfgxx0002/tcfgxx0002.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+. ../../etc/config
+. ../../libs/utils
+
+${KAMBIN} -P ${KAMPID} -w ${KAMRUN} -Y ${KAMRUN} -a no
+ret=$?
+sleep 1
+if [ ! "$ret" -eq 0 ] ; then
+    exit $ret
+fi
+sipsak -v -s sip:127.0.0.1
+ret=$?
+kill_pidfile ${KAMPID}
+
+exit $ret