  This is version 4.0.6 of the XFree86 cut of the xtest suite.  This
  version number has nothing to do with the XFree86 version numbers.

  Last modified: 26 January 2004

These are some brief notes to help in getting started with the
X test suite on XFree86 platforms.

The syntax for setting environment variables here is for csh/tcsh.
If you are using sh/ksh/bash, replace "setenv VAR value" with
"VAR=value; export VAR"

A build of the test suite requires about 50-60MB of disk space (including
a few largish log files).


1. The test/xsuite/xtest/tetbuild.cfg file is used to set platform-specific
   build parameters.  The XFree86 xtest source include pre-configured
   versions for Linux, BSD and SVR4 (Solaris).  To build the test suite,
   go to the test/xsuite directory and run:

     sh build.sh

   This will build the xtest framework (called "tet"), some diagnostic
   utilities for analysing the test results (like "blowup"), and the
   "link_scen" xtest scenario.  This just means that the a compact
   version of the test suite and its tests is built.  The "link" in
   "link_scen" means that groups of tests are linked together into single
   executables.

   If there is no pre-configured tetbuild.cfg file for your platform,
   start with tetbuild.cfg.std, edit according to the platform-specific
   comments, give it an appropriate name, and edit the test/xsuite/build.sh
   script to recognise and use it.  Please send any new/changed files to
   devel@xfree86.org for inclusion in future versions of this package.

2. The easiest way to run the test suite is to use the run.sh script
   in the test/xsuite directory.  This script will prompt for the run-specific
   values needed for the tetexec.cfg file, and create one to use from the
   information you enter and a template (tetbuild.cfg.tmpl).  The values
   are found from running 'xdpyinfo' against the server you're testing.
   Once they have been entered, the run.sh script will execute the test
   suite, and generate a report summary.  See below if you want to
   configure and run the test suite manually.

3. If you want to configure the test run manually, examine the run.sh
   script and the tetexec.cfg.tmpl template to see what values need to be
   configured.  You'll also need to set your PATH, and the TET_ROOT
   environment variable as indicated in the run.sh script.

4. Start up an X server on the machine you are testing on.  The X server
   should not have any clients running.  It should be started with the
   '-ac -s 0 -kb' flags so that access control, the screen saver, and
   the XKEYBOARD extension are all disabled.  Disabling access control
   ensures that the test suite will not have problems connecting to the
   target server.  Disabling the screen saver makes sure that it will
   not kick in during a test (it shouldn't anyway).  Disabling the
   XKEYBOARD extension ensures that some core requests behave as expected
   by the test.

5. Run the tests

   cd $TET_ROOT/xtest
   tcc -e -s link_scen xtest linkexec

   The report log for running the tests gets written to a subdirectory
   of the $TET_ROOT/xtest/results directory.  The subdirectories are
   numbered, and those for a test run (execution) end with 'e'.  A new
   directory is created for each run.

   The log file is called "journal".  The "tset" subdirectory contains
   subdirs for each test that fails *and* for which there are error
   bitmaps saved to help in debugging the problem.  The "blowup"
   utility can be used to view these.

   The "rpt" utility can be used to extract various information from
   the journal file.  For example. "rpt -p" gives a summary for each
   test + details for those which failed.  To specify which journal
   file to report on, add the "-f journal-name" flag.  Without this
   it uses the most recent one.

6. Running subsets of tests.

   It is possible to create new "scenario" files to run some subset
   of the tests.  Start with the $TET_ROOT/xtest/link_scen file, and
   edit the linkexec section to include only those tests you want to
   run.  Each line describes a group of tests.  The value in '{}'
   indicates which tests in each group are run.  'all' means run all
   of them.  Other legal values are comma separated ranges of numbers
   (e.g., {1,3-5}).

   To run a test with the new scenario file, use the same command as
   above, but replace "link_scen" with the name of the new file.

7. Running individual tests separately.

   Individual tests can be run by going to the directory containing
   the test (these are the subdirs of $TET_ROOT/xtest/tset/, for
   example $TET_ROOT/xtest/tset/CH03/stwdwbrdr), and using the 'pt'
   command.  The '-i' flag allows individual tests to be specified.
   For example, 'pt -i 1,3-5' will run tests 1, 3, 4, 5.  The result
   log for the test gets written to the file tet_xres.


For further information refer to $TET_ROOT/xtest/doc/userguide.mm.
There is a hardcopy version of this in the main X distribution
(in xc/doc/hardcopy/test/xsuite/userguide.PS.Z).



$XFree86: test/xsuite/NOTES.xf86,v 1.14 2004/01/26 15:25:53 dawes Exp $
