testsuite: add README file

Change-Id: I4f1a0bab9b1ca6bc8cbe455ec751096271a7b87b

diff --git a/Makefile.am b/Makefile.am
index 6d6b815..951bf77 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -215,6 +215,10 @@ dlogconf_DATA = \
 
 bin_SCRIPTS = dlog_test
 
+docdir = $(datadir)/doc/dlog
+doc_DATA = \
+       README.testsuite
+
 dox::
        doxygen
 

diff --git a/configs/99-dlog-logger.disable-platform-logging-for-testsuite.conf b/configs/99-dlog-logger.disable-platform-logging-for-testsuite.conf
index 766cab6..9df8a16 100644 (file)
--- a/configs/99-dlog-logger.disable-platform-logging-for-testsuite.conf
+++ b/configs/99-dlog-logger.disable-platform-logging-for-testsuite.conf
@@ -1 +1,4 @@
+# dlog testsuite - disable platform logging when performing logger backend tests
+# for more information please read /usr/share/doc/dlog/README.testsuite
+
 plog=0

diff --git a/configure.ac b/configure.ac
index 94e859a..d16022f 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -56,6 +56,7 @@ AC_SUBST([datadir])
 AC_SUBST([libexecdir])
 AC_CONFIG_FILES([Makefile dlog.pc]
                 [dlog_test:tests/dlog_test.in]
+                [README.testsuite:tests/README.testsuite.in]
                 [configs/dlog_logger.service])
 AC_OUTPUT
 

diff --git a/packaging/dlog.spec b/packaging/dlog.spec
index e64f244..956bf1f 100644 (file)
--- a/packaging/dlog.spec
+++ b/packaging/dlog.spec
@@ -218,6 +218,7 @@ fi
 %files -n dlog-tests
 %manifest dlog.manifest
 %{_bindir}/dlog_test
+/usr/share/doc/dlog/README.testsuite
 %{_libexecdir}/libdlog/perf_libdlog
 %{_libexecdir}/libdlog/test_libdlog
 %{_datadir}/dlog-pipe.conf.test
@@ -231,4 +232,6 @@ echo "Warning! Installation of dlog-tests will break platform logging."
 echo "This is done intentionally, to make logger backend testing possible."
 echo "To restore normal behavior, please uninstall dlog-tests package."
 echo ""
+echo "For more information please read the /usr/share/doc/dlog/README.testsuite file"
+echo ""
 echo "A reboot is required to properly configure logger backend for testing."

diff --git a/tests/README.testsuite.in b/tests/README.testsuite.in
new file mode 100644 (file)
index 0000000..2ea4a79
--- /dev/null
+++ b/tests/README.testsuite.in
@@ -0,0 +1,74 @@
+The dlog testsuite consists of a bash script and config files, shipped as a
+separate rpm file. The script is capable of testing both backends, chosen by
+providing proper argument:
+- for pipe backend:
+$ @bindir@/dlog_test pipe
+- for android logger backend:
+$ @bindir@/dlog_test logger
+
+The test environment setup is separate for both backends but performed tests
+are the same. Pipe backend environment setup looks as follows:
+- a proper config file is installed by rpm in @datadir@/dlog-pipe.conf.test.It
+stores paths to sockets used by daemon, util and libdlog based apps during tests
+which are separate from those used in production mode
+- DLOG_CONFIG_PATH envirinment variable is set to point at installed config file
+- a dlog daemon is started, it creates pipe sockets in location specified in
+config file pointed by DLOG_CONFIG_PATH env variable - /var/lib/dlog-tests/
+- testsuite tests are performed, dlogutil, dlogsend and libdlog based test
+apps use socket files specified in config file pointed by DLOG_CONFIG_PATH env
+variable
+- a test summary is printed, showing total, failed and passed tests count
+- daemon and all test apps are killed on exit
+
+Android logger testing is a little bit more tricky, since we cannot just run
+separate instance of daemon and communicate with it using separate sockets.
+It uses a kernel buffer which is system-wide and shared between all applications
+that wish to read or write log entries. Since there are multiple applications
+running on target and utilizing dlog all the time, it would be hard to
+read/write test log entries along with them and be 100% sure that no test log
+entries are lost (for example by overwriting them by entries written by other
+applications). However, there is a configuration setting called "platform
+logging", normally set to 1, which enables or disables writing to all buffers
+except apps buffer.
+
+Taking this into account, android logger environment setup works as follows:
+- an overlay config file is installed in
+@sysconfdir@/dlog.conf.d/99-dlog-logger.disable-platform-logging-for-testsuite.conf.
+It contains only one config entry that disables platform logging. It's being
+interpreted as a last config file, so we can be sure nothing else overwrites
+this setting. The bottleneck of this approach is that since we need to be sure
+that all system apps using libdlog will take this setting into account, a reboot
+is required after installing testsuite.
+- along with an overlay config file, a proper test config file is installed by
+rpm in @datadir@/dlog-logger.conf.test. It contains standard settings for
+android backend, but it has platform logging ENABLED
+- after reboot, all buffer except apps buffer are free of any log entries
+(platform logging disabled)
+- DLOG_CONFIG_PATH envirinment variable is set to point at installed config file
+@datadir@/dlog-logger.conf.test. It has platform logging enabled, so all
+dlogutil, dlogsend and libdlog based applications run from now on in this
+environment will have write access to all buffers.
+- testsuite tests are performed, both dlogutil and libdlog test apps use
+settings specified in config file pointed by DLOG_CONFIG_PATH env variable
+- a test summary is printed, showing total, failed and passed tests count
+- since an overlay config file is installed in a standard config files location
+and is interpreted on each startup, it's advised to uninstall dlog testsuite
+after performing tests. This will remove the file and enable platform logging to
+all system applications.
+
+Tests are common for both backends and consist of testing if:
+- dlogutil -d quits after printing logs
+- -t and -u arguments are parsed properly
+- limiting printed log count with -t works as expected
+- reading from an unknown buffer returns an error
+- ireading from empty buffer returns zero entries
+- dlogutil -c empties all buffers
+- writing to an empty buffer works as expected
+- log level filters work
+- "silent" filter works
+- writing buffer size with dlogutil -g works as expected
+- reading all entries to a single file works
+- reading all entries to rotating files works
+- all print formats work as expected (regex based matching)
+- pid/tid filtering works
+- sorting by timestamp works