[#3493] Document running unit tests with root privileges

diff --git a/doc/devel/unit-tests.dox b/doc/devel/unit-tests.dox
index 7d2a9246ba351f8de8740d9eb85b10b956e0bb63..86a49c9df7dd0795d5880cc5f8eef4615e62251b 100644 (file)
--- a/doc/devel/unit-tests.dox
+++ b/doc/devel/unit-tests.dox
@@ -416,6 +416,26 @@ settings which are not allowed by default Kerberos system configuration.
 A simple workaround is to set the KRB5_CONFIG environment variable to
 a random value that doesn't match a file (e.g. KRB5_CONFIG=).
 
+@section unitTestsRootPrivileges Running Unit Tests with Root Privileges
+
+Some unit tests require root privileges to run, including:
+
+- some packet filtering unit tests
+- some ping check unit tests
+
+To maximize the chance that these tests are always run during development,
+there is an attempt done to run them automatically with elevated privileges
+when ``meson test`` is run. In order to do that, at setup-time, Meson checks if
+sudo can be run non-interactively. If not, the tests that require root
+privileges are part of the regular targets ``dhcp-ping-check-tests`` and
+``kea-dhcp-tests``. If the check passes, then the tests are included in special
+targets ``sudo-dhcp-ping-check-tests`` and ``sudo-kea-dhcp-tests``. These
+targets run the unit test binaries prefixed with sudo which per the check done
+priorly, should be possible in a non-interactive manner. The tests requiring
+root privileges are also part of a special suite called ``sudo-tests`` which
+can be run exclusively with the ``--suite`` flag, or can be excluded with the
+``--no-suite`` flag.
+
 @section writingShellScriptsAndTests Writing shell scripts and tests
 
 Shell tests are `shellcheck`ed. But there are other writing practices that are