8 files changed, 65 insertions, 0 deletions
diff --git a/test/coverage.md b/test/coverage.md
new file mode 100644
index 000000000..c5ee8b071
--- /dev/null
+++ b/test/coverage.md
@@ -0,0 +1,58 @@
+Coverage collection explained
+=============================
+
+Hi mate. In short, you don't wanna know this. Believe me, you don't. Please, close this file and forget about it.
+
+Surely? You still here?
+
+Please, stop it until it's too late.
+
+You were warned.
+
+
+Preamble
+--------
+RSPAMD is written mainly in two languages: C and Lua. Coverage for each of them is being collected using different 
+tools and approaches and is sent into [coveralls.io](https://coveralls.io).
+Each approach is not quite compatible to other tools. This document describes how we crutch them to work together.
+
+
+C coverage
+----------
+In general, pretty boring. When you run `cmake` with "-DENABLE_COVERAGE=ON" flag, it adds "--coverage" flag to both
+CFLAGS and LDFLAGS. So that each run of generated binary will create `*.gcda` file containing coverage data.
+
+However, there are some moment to highlight:
+
+- RSPAMD is run under "nobody" user. Hence, directories and files should be writable for this user. 
+- To make it possible, we explicitly run `umask 0000` in "build" and "functional" stages in .circleci/config.yml
+- After run, we persist coverage data in "coverage.${CIRCLE\_JOB}.dump" during this build flow, see `capture_coverage_data`,
+  to use it on the final stage.
+- we user `cpp-coverals` because it is able to save data for coveralls without actually sending it. We send on our own
+  along with Lua-coverage.
+
+Lua coverage
+------------
+Lua coverage is collected for unit-tests and functional test suite. 
+First part contains nothing interesting, just see `test/lua/tests.lua`.
+
+"Functional" part is completely unobvious.
+
+1. Coverage collecting is initiated and dumped in `test/functional/lua/test_coverage.lua` (there are a lot of comments inside).
+   This file should be included on the very early stage of test run. Usually it's included via config.
+2. Coverage is dumped into ${TMPDIR}/%{woker_name}.luacov.stats.out
+3. All worker coverage reports are merged into `lua_coverage_report.json` (see `collect_lua_coverage()`)
+4. finally, `lua_coverage_report.json` is persisted in build flow (see `functional` stage)
+
+Altogether
+----------
+
+Finally, we get all the reports:
+
+- `coverage.functional.dump` 
+- `coverage.rspamd-test.dump`
+- `lua_coverage_report.json`
+- `unit_test_lua.json`
+
+and merge them and send the resulting report using `test/functional/util/merge_coveralls.py`. Also, this scripts maps installed
+paths into corresponding repository paths and removes unneeded files (i.e. test sources).
diff --git a/test/functional/configs/dkim.conf b/test/functional/configs/dkim.conf
index 4ac7bf6b5..9307476c1 100644
--- a/test/functional/configs/dkim.conf
+++ b/test/functional/configs/dkim.conf
@@ -78,3 +78,4 @@ EOD;
   trusted_only = false;
   skip_multi = false;
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
diff --git a/test/functional/configs/fuzzy.conf b/test/functional/configs/fuzzy.conf
index 6232b567d..3eb554dc8 100644
--- a/test/functional/configs/fuzzy.conf
+++ b/test/functional/configs/fuzzy.conf
@@ -1,6 +1,7 @@
 redis {
   servers = "${REDIS_ADDR}:${REDIS_PORT}";
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
 options = {
 	filters = "fuzzy_check";
 	pidfile = "${TMPDIR}/rspamd.pid";
diff --git a/test/functional/configs/milter.conf b/test/functional/configs/milter.conf
index 004bf8b5f..789040e68 100644
--- a/test/functional/configs/milter.conf
+++ b/test/functional/configs/milter.conf
@@ -50,6 +50,7 @@ worker {
 modules {
     path = "${TESTDIR}/../../src/plugins/lua/"
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
 lua = "${INSTALLROOT}/share/rspamd/rules/rspamd.lua"
 lua = "${TESTDIR}/lua/params.lua"
 milter_headers {
diff --git a/test/functional/configs/password.conf b/test/functional/configs/password.conf
index 9c06e7c7b..922301844 100644
--- a/test/functional/configs/password.conf
+++ b/test/functional/configs/password.conf
@@ -42,3 +42,4 @@ worker {
 	enable_password = ${ENABLE_PASSWORD};
 	stats_path = "${TMPDIR}/stats.ucl";
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
diff --git a/test/functional/configs/proxy.conf b/test/functional/configs/proxy.conf
index bca691510..01217c113 100644
--- a/test/functional/configs/proxy.conf
+++ b/test/functional/configs/proxy.conf
@@ -20,3 +20,4 @@ worker "rspamd_proxy" {
     }
     count = 1;
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
diff --git a/test/functional/configs/spamassassin.conf b/test/functional/configs/spamassassin.conf
index eabefea2c..53aa89ec7 100644
--- a/test/functional/configs/spamassassin.conf
+++ b/test/functional/configs/spamassassin.conf
@@ -1,4 +1,5 @@
 spamassassin {
 	rules = "${TESTDIR}/configs/spamassassin.rules"
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
 lua = "${TESTDIR}/lua/simple.lua"
diff --git a/test/functional/configs/stats.conf b/test/functional/configs/stats.conf
index e770de2e8..f79729f39 100644
--- a/test/functional/configs/stats.conf
+++ b/test/functional/configs/stats.conf
@@ -72,5 +72,6 @@ classifier {
 		${REDIS_SERVER}
 	}
 }
+lua = "${TESTDIR}/lua/test_coverage.lua";
 
 settings {}