Documentation: Document the system testsuites.

I hadn't run this before so I had to discover how it worked.

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Numan Siddique <numans@ovn.org>

Documentation/topics/testing.rst

@@ -188,3 +188,47 @@ Instructions to setup travis-ci for your GitHub repository:
 
 4. Pushing a commit to the repository which breaks the build or the
    testsuite will now trigger a email sent to mylist@mydomain.org
+
+Datapath testing
+~~~~~~~~~~~~~~~~
+
+OVN includes a suite of tests specifically for datapath functionality.
+The datapath tests make some assumptions about the environment.  They
+must be run under root privileges on a Linux system with support for
+network namespaces.  Make sure no other Open vSwitch instance is
+running the test suite.  These tests may take several minutes to
+complete, and cannot be run in parallel.
+
+To invoke the datapath testsuite with the OVS userspace datapath,
+run::
+
+    $ make check-system-userspace
+
+The results of the userspace testsuite appear in
+``tests/system-userspace-testsuite.dir``.
+
+To invoke the datapath testsuite with the OVS kernel datapath, run::
+
+    $ make check-kernel
+
+The results of the kernel testsuite appear in
+``tests/system-kmod-testsuite.dir``.
+
+The tests themselves must run as root.  If you do not run ``make`` as
+root, then you can specify a program to get superuser privileges as
+``SUDO=<program>``, e.g. the following uses ``sudo`` (the ``-E``
+option is needed to pass through environment variables)::
+
+    $ make check-system-userspace SUDO='sudo -E'
+
+The testsuite creates and destroys tap devices named ``ovs-netdev``
+and ``br0``.  If it is interrupted during a test, then before it can
+be restarted, you may need to destroy these devices with commands like
+the following::
+
+    $ ip tuntap del dev ovs-netdev mode tap
+    $ ip tuntap del dev br0 mode tap
+
+All the features documented under `Unit Tests`_ are available for the
+datapath testsuites, except that the datapath testsuites do not
+support running tests in parallel.

tests/automake.mk

@@ -155,11 +155,12 @@ check-helgrind: all $(valgrind_wrappers) $(check_DATA)
 # Run kmod tests. Assume kernel modules has been installed or linked into the kernel
 check-kernel: all
 	set $(SHELL) '$(SYSTEM_KMOD_TESTSUITE)' -C tests  AUTOTEST_PATH='$(AUTOTEST_PATH)'; \
-	"$$@" $(TESTSUITEFLAGS) -j1 || (test X'$(RECHECK)' = Xyes && "$$@" --recheck)
+	$(SUDO) "$$@" $(TESTSUITEFLAGS) -j1 || (test X'$(RECHECK)' = Xyes && $(SUDO) "$$@" --recheck)
 
-check-system-userspace: all
+
+check-system-userspace: all
 	set $(SHELL) '$(SYSTEM_USERSPACE_TESTSUITE)' -C tests  AUTOTEST_PATH='$(AUTOTEST_PATH)'; \
-	"$$@" $(TESTSUITEFLAGS) -j1 || (test X'$(RECHECK)' = Xyes && "$$@" --recheck)
+	$(SUDO) "$$@" $(TESTSUITEFLAGS) -j1 || (test X'$(RECHECK)' = Xyes && $(SUDO) "$$@" --recheck)
 
 clean-local:
 	test ! -f '$(TESTSUITE)' || $(SHELL) '$(TESTSUITE)' -C tests --clean