doc: update test suite page for ninja and other recent changes

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/test-suite.dox

@@ -1,18 +1,21 @@
 /**
 @page test-suite libinput test suite
 
-The libinput test suite is based on
+libinput ships with a number of tests all run automatically on `ninja test`.
-[Check](http://check.sourceforge.net/doc/check_html/) and runs automatically
+The primary test suite is the `libinput-test-suite-runner`. When testing,
-during `make check`. Check itself is wrapped into a libinput-specific test
+the `libinput-test-suite-runner` should always be invoked to check for
-suite called *litest*. Tests are found in `$srcdir/test/`, the main test
+behavior changes.
-suite is `libinput-test-suite-runner`.
 
-The test suite has a make-like job control enabled by the `-j` or `--jobs`
+The test suite runner uses
-flag and will fork off as many parallel processes as given by this flag. The
+[Check](http://check.sourceforge.net/doc/check_html/) underneath the hood
-default if unspecified is 8. When debugging a specific test case failure it
+but most of the functionality is abstracted into *litest* wrappers.
-is recommended to employ test filtures (see @ref test-filtering) and disable
+
-parallel tests. The test suite automatically disables parallel make when run
+The test suite runner has a make-like job control enabled by the `-j` or
-in gdb.
+`--jobs` flag and will fork off as many parallel processes as given by this
+flag. The default if unspecified is 8. When debugging a specific test case
+failure it is recommended to employ test filtures (see @ref test-filtering)
+and disable parallel tests. The test suite automatically disables parallel
+make when run in gdb.
 
 @section test-config X.Org config to avoid interference
 
@@ -28,35 +31,67 @@ with your desktop.
 
 Most tests require the creation of uinput devices and access to the
 resulting `/dev/input/eventX` nodes. Some tests require temporary udev rules.
-<b>This usually requires the tests to be run as root</b>.
+<b>This usually requires the tests to be run as root</b>. If not run as
+root, the test suite runner will exit with status 77, interpreted as
+"skipped" by ninja.
 
 @section test-filtering Selective running of tests
 
-litest's tests are grouped by test groups and devices. A test group is e.g.
+litest's tests are grouped into test groups, test names and devices. A test
-"touchpad:tap" and incorporates all tapping-related tests for touchpads.
+group is e.g.  "touchpad:tap" and incorporates all tapping-related tests for
-Each test function is (usually) run with one or more specific devices.
+touchpads. Each test function is (usually) run with one or more specific
-The `--list` commandline argument shows the list of suites and tests.
+devices. The `--list` commandline argument shows the list of suites and
+tests. This is useful when trying to figure out if a specific test is
+run for a device.
+
 @code
 $ ./test/libinput-test-suite-runner --list
-device:wheel:
+...
-	wheel only
+pointer:left-handed:
-	blackwidow
+	pointer_left_handed_during_click_multiple_buttons:
-device:invalid devices:
+		trackpoint
-	no device
+		ms-surface-cover
-device:group:
+		mouse-wheelclickcount
-	no device
+		mouse-wheelclickangle
-	logitech trackball
+		low-dpi-mouse
-	MS surface cover
+		mouse-roccat
-	mouse_roccat
+		mouse-wheel-tilt
-	wheel only
+		mouse
-	blackwidow
+		logitech-trackball
+		cyborg-rat
+		magicmouse
+	pointer_left_handed_during_click:
+		trackpoint
+		ms-surface-cover
+		mouse-wheelclickcount
+		mouse-wheelclickangle
+		low-dpi-mouse
+		mouse-roccat
+		mouse-wheel-tilt
+		mouse
+		logitech-trackball
+		cyborg-rat
+		litest-magicmouse-device
+	pointer_left_handed:
+		trackpoint
+		ms-surface-cover
+		mouse-wheelclickcount
+		mouse-wheelclickangle
+		low-dpi-mouse
+		mouse-roccat
+		mouse-wheel-tilt
+		mouse
 ...
 @endcode
 
-In the above example, the "device:wheel" suite is run for the "wheel only" and
+In the above example, the "pointer:left-handed" suite contains multiple
-the "blackwidow" device. Both devices are automatically instantiated through
+tests, e.g. "pointer_left_handed_during_click" (this is also the function
-uinput by litest. The "no device" entry signals that litest does not
+name of the test, making it easy to grep for). This particular test is run
-instantiate a uinput device for a specific test (though the test itself may
+for various devices including the trackpoint device and the magic mouse
+device.
+
+The "no device" entry signals that litest does not instantiate a uinput
+device for a specific test (though the test itself may
 instantiate one).
 
 The `--filter-test` argument enables selective running of tests through
@@ -93,7 +128,7 @@ environment variable, if set, also enables verbose mode.
 
 @code
 $ ./test/libinput-test-suite-runner --verbose
-$ LITEST_VERBOSE=1 make check
+$ LITEST_VERBOSE=1 ninja test
 @endcode
 
 */