diff --git a/doc/user/test-suite.rst b/doc/user/test-suite.rst index 1f6dc394..355063d5 100644 --- a/doc/user/test-suite.rst +++ b/doc/user/test-suite.rst @@ -5,8 +5,8 @@ libinput test suite ============================================================================== 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 +The primary test suite is the ``libinput-test-suite``. When testing, +the ``libinput-test-suite`` should always be invoked to check for behavior changes. The test suite relies on the kernel and udev to function correctly. It is not suitable for running inside containers. @@ -66,7 +66,7 @@ run for a device. :: - $ ./builddir/libinput-test-suite-runner --list + $ ./builddir/libinput-test-suite --list ... pointer:left-handed: pointer_left_handed_during_click_multiple_buttons: @@ -121,7 +121,7 @@ basic shell-style function name matching. For example: :: - $ ./builddir/libinput-test-suite-runner --filter-test="*1fg_tap*" + $ ./builddir/libinput-test-suite --filter-test="*1fg_tap*" The ``--filter-device`` argument enables selective running of tests through @@ -131,7 +131,7 @@ litest-specific shortnames, see the output of ``--list``. For example: :: - $ ./builddir/libinput-test-suite-runner --filter-device="synaptics*" + $ ./builddir/libinput-test-suite --filter-device="synaptics*" The ``--filter-group`` argument enables selective running of test groups @@ -141,7 +141,7 @@ litest-specific test groups, see the output of ``--list``. For example: :: - $ ./builddir/libinput-test-suite-runner --filter-group="touchpad:*hover*" + $ ./builddir/libinput-test-suite --filter-group="touchpad:*hover*" The ``--filter-device`` and ``--filter-group`` arguments can be combined with @@ -160,5 +160,33 @@ environment variable, if set, also enables verbose mode. :: - $ ./builddir/libinput-test-suite-runner --verbose + $ ./builddir/libinput-test-suite --verbose $ LITEST_VERBOSE=1 ninja test + +.. _test-installed: + +------------------------------------------------------------------------------ +Installing the test suite +------------------------------------------------------------------------------ + +If libinput is configured to install the tests, the test suite is available +as the ``libinput test-suite`` command. When run as installed binary, the +behavior of the test suite changes: + +- the ``libinput.so`` used is the one in the library lookup paths +- no system-wide quirks are installed by the test suite, only those specific + to the test devices +- test device-specific quirks are installed in the system-wide quirks + directory, usually ``/usr/share/libinput/``. + +It is not advisable to run ``libinput test-suite`` on a production machine. +Data loss may occur. The primary use-case for the installed test suite is +verification of distribution composes. + +.. note:: The ``prefix`` is still used by the test suite. For verification + of a system package, the test suite must be configured with the same prefix. + +To configure libinput to install the tests, use the ``-Dinstall-tests=true`` +meson option:: + + $ meson builddir -Dtests=true -Dinstall-tests=true diff --git a/meson.build b/meson.build index 1ca9ae7f..3e3a27b0 100644 --- a/meson.build +++ b/meson.build @@ -406,6 +406,7 @@ dep_tools_shared = declare_dependency(link_with : lib_tools_shared, man_config = configuration_data() man_config.set('LIBINPUT_VERSION', meson.project_version()) +man_config.set('LIBINPUT_DATA_DIR', dir_data) deps_tools = [ dep_tools_shared, dep_libinput ] libinput_debug_events_sources = [ 'tools/libinput-debug-events.c' ] @@ -843,11 +844,19 @@ if get_option('tests') 'test/test-switch.c', 'test/test-quirks.c', ] - libinput_test_runner = executable('libinput-test-suite-runner', + libinput_test_runner = executable('libinput-test-suite', libinput_test_runner_sources, include_directories : [includes_src, includes_include], dependencies : deps_litest, - install : false) + install_dir : libinput_tool_path, + install : get_option('install-tests')) + configure_file(input : 'test/libinput-test-suite.man', + output : 'libinput-test-suite.1', + configuration : man_config, + install : true, + install_dir : dir_man1, + ) + test('libinput-test-suite-runner', libinput_test_runner, timeout : 1200) diff --git a/meson_options.txt b/meson_options.txt index fd014965..6d502637 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -18,6 +18,10 @@ option('tests', type: 'boolean', value: true, description: 'Build the tests [default=true]') +option('install-tests', + type: 'boolean', + value: false, + description: 'Install the libinput test command [default=false]') option('documentation', type: 'boolean', value: true, diff --git a/test/libinput-test-suite.man b/test/libinput-test-suite.man new file mode 100644 index 00000000..906dfe63 --- /dev/null +++ b/test/libinput-test-suite.man @@ -0,0 +1,95 @@ +.TH libinput-test-suite "1" "" "libinput @LIBINPUT_VERSION@" "libinput Manual" +.SH NAME +libinput\-test\-suite \- run the libinput test suite +.SH SYNOPSIS +.B libinput test\-suite [OPTIONS] +.PP +.SH DESCRIPTION +.PP +The +.B "libinput test\-suite" +command runs the libinput test suite. +Its primary purpose is to verify distribution composes after package updates. Test +suite failures usually indicate missing patches and/or incompatible lower +system layers. +.PP +.B The test suite should not be run by users. Data loss is possible. +.PP +The test suite must be run as root. The test suite installs several files +on the host system (see section \fBFILES\fR), runs system commands and +creates virtual kernel devices via uinput. These devices will interfere with +any active session and may cause data loss. +.PP +It is recommended that the test suite is run in a virtual machine and/or on +a system not otherwise in use. A graphical environment is not required to +run the test suite. + +.SH OPTIONS +Note that the options may change in future releases of libinput. Test names, +test device names and test group names may change at any time. +.TP 8 +.B \-\-filter\-test \fI"testname"\fB +A glob limiting the tests to run. Specifying a filter sets the +\fB\-\-jobs\fR default to 1. +.TP 8 +.B \-\-filter\-device \fI"devicename"\fB +A glob limiting the devices to run tests for. Specifying a filter sets the +\fB\-\-jobs\fR default to 1. +.TP 8 +.B \-\-filter\-group \fI"groupname"\fB +A glob limiting the tests to (arbitrarily named) groups. Specifying a filter sets the +\fB\-\-jobs\fR default to 1. +.TP 8 +.B \-\-filter\-deviceless +\fBFOR INTERNAL USE ONLY\fR +.TP 8 +.B \-h, \-\-help +Print help +.TP 8 +.B \-j, \-\-jobs 8 +Number of parallel processes to run. Default: 8. +.TP 8 +.B \-\-list +List all test cases and the devices they are run for. Test names, test device +names and test group names may change at any time. +.TP 8 +.B \-\-verbose +Enable verbose output, including libinput debug messages. +.SH FILES +The following directories are modified: + +.TP 8 +.B @LIBINPUT_DATA_DIR@ +Test device-specific quirks are installed in this directory with a custom +prefix. Files in this directory are untouched but new files are installed +and removed on exit. Existing files (e.g. from a previous aborted run) with +the same name will be silently overwritten and removed. +.TP 8 +.B /run/udev/rules.d +Test-specific udev rules are installed in this directory and removed on +exit. +.PP +.SH SYSTEM SETUP +The \fBxorg.conf.d(5)\fR snippet below ensures the X server ignores the test +devices created by this test suite: +.PP +.RS 4 +.nf +.B "Section ""InputClass"" +.B " Identifier ""libinput test suite blacklist"" +.B " MatchProduct ""litest"" +.B " Option ""Ignore"" ""on"" +.B "EndSection" +.fi +.RE +.PP +No configuration is required for Wayland compositors. libinput's default +mode will ignore test devices from this test suite. +.SH BUGS +Some tests are sensitive to timing. Where a system is under heavy load, +a test may fail. Re-running the test with \fB\-\-filter-test\fR can help +verify whether a test case failure was a true failure. +.SH LIBINPUT +Part of the +.B libinput(1) +suite diff --git a/test/litest.c b/test/litest.c index 5e7c0f23..666abc8b 100644 --- a/test/litest.c +++ b/test/litest.c @@ -58,6 +58,7 @@ #include "litest-int.h" #include "libinput-util.h" #include "quirks.h" +#include "builddir.h" #include @@ -3900,26 +3901,31 @@ litest_parse_argv(int argc, char **argv) OPT_JOBS, OPT_LIST, OPT_VERBOSE, - OPT_SYSTEM_QUIRKS, }; static const struct option opts[] = { { "filter-test", 1, 0, OPT_FILTER_TEST }, { "filter-device", 1, 0, OPT_FILTER_DEVICE }, { "filter-group", 1, 0, OPT_FILTER_GROUP }, { "filter-deviceless", 0, 0, OPT_FILTER_DEVICELESS }, - { "use-system-quirks", 0, 0, OPT_SYSTEM_QUIRKS }, { "jobs", 1, 0, OPT_JOBS }, { "list", 0, 0, OPT_LIST }, { "verbose", 0, 0, OPT_VERBOSE }, { "help", 0, 0, 'h'}, { 0, 0, 0, 0} }; - enum { JOBS_DEFAULT, JOBS_SINGLE, JOBS_CUSTOM } want_jobs = JOBS_DEFAULT; + char *builddir; + + /* If we are not running from the builddir, we assume we're running + * against the system as installed */ + builddir = builddir_lookup(); + if (!builddir) + skip_quirks_install = true; + free(builddir); if (in_debugger) want_jobs = JOBS_SINGLE; @@ -3984,9 +3990,6 @@ litest_parse_argv(int argc, char **argv) case OPT_FILTER_DEVICELESS: run_deviceless = true; break; - case OPT_SYSTEM_QUIRKS: - skip_quirks_install = true; - break; } }