This is a test suite for X.Org tests.

== Building the code ==
Required libraries:
 xorg-gtest: http://cgit.freedesktop.org/xorg/test/xorg-gtest/

Both of these are source libraries, but they need to be built and installed
for this repository to build.

=== Building xorg-gtest ===
  ./autogen.sh
  ./configure --prefix=$HOME/testing
  make && make install

Notes:
* The repository must be installed for the pkg-config file to provide the
   right CFLAGS and include paths.

=== Building this repository ===
  export ACLOCAL_PATH="-I $HOME/testing/aclocal"
  export ACLOCAL="aclocal -I $ACLOCAL_PATH"
  export PKG_CONFIG_PATH="$HOME/testing/lib/pkgconfig"
  ./autogen.sh --prefix=$HOME/testing
  make

Notes:
* This repo does not need to be installed.
* The default path for config and log files is /tmp. Tests that fail will
  leave their files there for inspection.
  Use --with-logpath=/some/path to change this path

== Running the tests ==
Tests can be run by "make check", or one-by-one. 

Most tests start up some X server, so it is advisable to shut down any X
server on the test box. Some tests only start Xdummy, but do add
virtual input devices that may mess with the current session. Again, it is
advisable to shut down any X server on the test box.

For controlling test output (e.g. xml reporting), refer to
http://code.google.com/p/googletest/wiki/AdvancedGuide#Controlling_Test_Output

== Debugging test failures  ==
To run a subset of tests within a test case, filter on the test name. For
example,

        ./test-input-load --gtest_filter=InputDriverTest.DriverDevice/7

only runs the 7th test in the InputDriverTest/DriverDevice test case. Refer
to the googletest wiki for more information.
http://code.google.com/p/googletest/wiki/AdvancedGuide#Running_a_Subset_of_the_Tests

xorg-gtest supports the environment variable XORG_GTEST_XSERVER_SIGSTOP. If
set, the test will SIGSTOP itself once a server has been started. This
allows to investigate logs or attach gdb to the server process.

For further environment variables please refer to the xorg-gtest README
http://cgit.freedesktop.org/xorg/test/xorg-gtest/tree/README

=== Avoiding interference with your running server ===
Many of the tests will create uinput devices that, usually, will also be picked
up as devices in your current X session. This will result in pointer movement,
random clicks, etc. in your current session. This is not a fault of the tests.

To avoid this interference the current X server must be configured to either
ignore input device hotplugging altogether (Option AutoAddDevices off, see
xorg.conf(5)) or, a smaller sledgehammer, be configured to ignore virtual
devices. The udev rule below applies a tag to every virtual device. An
xorg.conf snippet (below) matches against this tag and tells the server to
ignore those. Restart the X server to let the changes take effect.

BEWARE: adding this xorg.conf snippet will disable _all_ virtual input
devices in your current X session.

$> cat /etc/udev/rules.d/99-tag-virtual-devices.rules
# tag all virtual devices as virtual devices, so an xorg.conf snippet can be
# set up to ignore those.

ACTION!="add|change", GOTO="tag_virtual_devices_end"
KERNEL!="event[0-9]*", GOTO="tag_virtual_devices_end"

ENV{DEVPATH}=="/devices/virtual/*", ENV{ID_INPUT.tags}+="virtualdevice"

LABEL="tag_virtual_devices_end"

$> cat /etc/X11/xorg.conf.d/99-ignore-virtual-devices.conf
# Ignore all devices with ID_INPUT.tags set to "virtualdevice"
Section "InputClass"
  Identifier "ignore virtual devices"
  MatchTag "virtualdevice"
  Option "Ignore" "on"
EndSection


== Writing tests ==
Please refer to the HACKING document