DESCRIPTION
--------------------------------------------------------------------------------

Wayland Functional Integration Test Suite (aka. wayland-fits)

Wayland-fits is a fully automated functional integration test suite.  It's
main purpose is to test the functionality and integration of client-side
(i.e. toolkit) and server-side (compositor) implementations of the Wayland
protocol.  It includes tests that validate user input events originating from
the server-side or from an emulated system-level device (depends on the type
of backend used).  There are also tests with emphasis on cross-validating client
and server states.

The test framework design includes a wayland-fits test extension that defines two
Wayland protocols. The first protocol is a interface for generating input events
on the server-side (e.g. mouse, keyboard, touch). The second is a interface for
querying state information from the server/compositor.  This extension is
exploited by most of the tests.  Thus, to run these tests on a particular Wayland
server/compositor, there has to be an implementation of this extension for that
compositor (i.e. src/extensions/<compositor>).

A Weston implementation of the wayland-fits test extension (weston-wfits.so) is
included as a pluggable module to Weston.  For the drm and x11 backends, it
employs uinput to emulate various input devices.  For the headless backend, it
uses the weston input API's directly.  It also exposes various other
internal compositor states that can be queried by tests, such as surface
geometry and pointer coordinates.


LICENSE
--------------------------------------------------------------------------------

MIT - see COPYING file


REQUIREMENTS
--------------------------------------------------------------------------------

 * check - A unit testing framework for C >= 0.9.8
 * boost - Boost C++ libraries >= 1.48.0
 * Wayland >= 1.2.0
 * Weston >= 1.2.0

 Optional:
 * EFL/Elementary Wayland >= 1.7.6
 * GTK+ Wayland
 * Cogl/Clutter Wayland (future development)
 * Qt Wayland (future development)


COMPILING
--------------------------------------------------------------------------------

 $ ./autogen.sh
 $ make
 $ make install

 See http://wayland.freedesktop.org/build.html for more information on general
 Wayland building requirements/options (e.g. installing in a custom location).


RUNNING
--------------------------------------------------------------------------------

 You need to load the wayland-fits test extension into your Wayland compositor (Note:
 an implementation of the wfits test extension is needed for each compositor,
 currently Weston is the only one supported at the moment):

 For Weston, this is "weston-wfits.so" and it's loaded with the --modules option:

  $ weston --modules=weston-wfits.so &

  NOTE: The weston-wfits.so module supports x11-backend, drm-backend, and the
  headless-backend.  However, not all tests can be run on the headless-backend;
  particularly the egl-based ones.

  NOTE: Ensure that all shell animations are turned off (i.e. in weston.ini).
  These animations have a tendency to break the input-based test cases.

 If you define the environment variable WESTON_WFITS_INPUT_EMULATOR=<method>, the
 weston-wfits.so module will use that method when it loads at startup.  The
 available methods are 'notify' and 'uinput'.  The 'notify' method does not require
 a suid/root weston whereas the 'uinput' method does.

 Next, run the test suite:

  $ wfits

 You can filter the tests you want to run by using the --filter option.  This
 option takes a boost-regex style expression (POSIX-extended, case-ignored),
 for example:

  $ wfits --filter core.*
  $ wfits --filter .*pointer.*

 Run 'wfits --help' for more options.
 
 NOTE: You can set the environment variable "CK_FORK=no" to have wfits run in non-forked
 test mode.  This is especially useful for debugging with gdb
 (e.g. CK_FORK=no gdb --args wfits --filter <testname>).
 

BUGS
--------------------------------------------------------------------------------

 If a test is failing, try to determine if it's an actual bug in the test or a
 bug in the component that is being tested.  If it's a bug in the test, file at:

  https://github.com/01org/wayland-fits/issues

 Otherwise, file a bug in the appropriate database assigned to the failing
 Wayland component if one does not already exist.


CONTRIBUTING
--------------------------------------------------------------------------------

 Send patches to "wayland-devel@lists.freedesktop.org" with the subject prefix
 of "[PATCH wfits]".  Git example:

   git format-patch --subject-prefix="PATCH wfits" ...