fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-02-04 05:50:26 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2017-11-02 10:23:50 +10:00
parent 04c6439449
commit b15b66616e
1 changed files with 68 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
doc/test-suite.dox
View file

@ -1,18 +1,21 @@
/**
@page test-suite libinput test suite
The libinput test suite is based on
[Check](http://check.sourceforge.net/doc/check_html/) and runs automatically
during `make check`. Check itself is wrapped into a libinput-specific test
suite called *litest*. Tests are found in `$srcdir/test/`, the main test
suite is `libinput-test-suite-runner`.
libinput ships with a number of tests all run automatically on `ninja test`.
The primary test suite is the `libinput-test-suite-runner`. When testing,
the `libinput-test-suite-runner` should always be invoked to check for
behavior changes.
The test suite has a make-like job control enabled by the `-j` or `--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.
The test suite runner uses
[Check](http://check.sourceforge.net/doc/check_html/) underneath the hood
but most of the functionality is abstracted into *litest* wrappers.
The test suite runner has a make-like job control enabled by the `-j` or
`--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.
"touchpad:tap" and incorporates all tapping-related tests for touchpads.
Each test function is (usually) run with one or more specific devices.
The `--list` commandline argument shows the list of suites and tests.
litest's tests are grouped into test groups, test names and devices. A test
group is e.g. "touchpad:tap" and incorporates all tapping-related tests for
touchpads. Each test function is (usually) run with one or more specific
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
blackwidow
device:invalid devices:
no device
device:group:
no device
logitech trackball
MS surface cover
mouse_roccat
wheel only
blackwidow
...
pointer:left-handed:
pointer_left_handed_during_click_multiple_buttons:
trackpoint
ms-surface-cover
mouse-wheelclickcount
mouse-wheelclickangle
low-dpi-mouse
mouse-roccat
mouse-wheel-tilt
mouse
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
the "blackwidow" device. Both devices are automatically instantiated through
uinput by litest. The "no device" entry signals that litest does not
instantiate a uinput device for a specific test (though the test itself may
In the above example, the "pointer:left-handed" suite contains multiple
tests, e.g. "pointer_left_handed_during_click" (this is also the function
name of the test, making it easy to grep for). This particular test is run
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
*/