--- /dev/null
+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