For Developers: Automated Testing

Unit Testing

The driver features a built-in test suite for white box testing. It can be triggered by running either make check (if building with autotools) or ninja test (if building with Meson).

How it works

Driver sources may contain functions decorated with a special TEST_CASE() macro inside a conditional #ifdef ENABLE_TESTS block. When you request the tests to be compiled, the build system defines ENABLE_TESTS and compiles all of these functions. The TEST_CASE() macro is defined in ./test/wacom-test-suite.h and primarily causes each of these functions to be stored in a special linker section named test_section. In addition to all the other functions compiled into the object, the build system also links in ./test/wacom-test-suite.c which contains a function named wcm_run_tests that runs all functions contained in this special test_section.

The output is either a binary whose main function calls wcm_run_tests (e.g. the xsetwacom test suite) or a shared object named wcm_drv_test.so which can be dynamically loaded and run by the trivial test-running program defined by ./test/wacom-tests.c.

Writing a test

Tip: Writing tests can be painful but they beat restarting X for quick input/output testing. Over time, the time spent writing tests pays off easily.

Test cases can be "normal" functions that live alongside the rest of the logic in a file. They should be contained in the #ifdef ENABLE_TESTS block at the end of the file. Test case names should be prefixed with test_ to make their purpose clear.

The test function itself must set up the required environment and then call the actual functions to test. Afterwards, use assert to ensure the right values are returned:

TEST_CASE(test_wcm_some_function)
{

  ... do some setup here

  othervalue = wcm_some_function(somevalue);
  assert(somevalue > othervalue);
  assert(othervalue >= 0);
  ...
}

Fuzz Testing

The xsetwacom tool can be built with a special "fuzz interface" that allows it to be connected to fuzzing tools like "afl-fuzz". When enabled, the tool will accept NUL-separated commands from stdin. This can be used to ensure the tool does not misbehave when fed arbitrary input.

To enable the fuzz interface, configure the driver with ./configure --enable-fuzz-interface or meson -Dfuzzinterface=true and build. The xsetwacom tool will afterwards use command-line arguments from stdin (e.g. echo -en 'get\09\0mode' | xsetwacom instead of xsetwacom get 9 mode)