path: root/xc/test/xsuite/xtest/doc/userguide.mm

.\" $XConsortium: userguide.mm,v 1.11 92/07/05 12:46:46 rws Exp dpw $
'
.ds dD User Guide for the X Test Suite
.so 00.header
'\"
'\" Start and end of a user-typed display
'\"
.de cS
.DS I
.ft C
.ps -2
..
.de cE
.ps +2
.ft R
.DE
..
'\" # Courier
.de C
\fC\\$1\fP\\$2\fC\\$3\fP\\$4\fC\\$5\fP\\$6
..
'\"	###
.H 1 "Introduction"
This document is a guide to installing and running
\*(xR of the \*(xT.
In order to do this, please work through all of the steps described
in this guide in order. Information on the content, purpose and goals of the 
\*(xT
is found in a series of appendices, which follow the installation 
instructions.
.P
Please read the "Release Notes for the \*(xT",
which describe particular features of this release.
.P
Further information, which would be required by a programmer to modify or extend 
the \*(xT, is contained in a separate document, "Programmers Guide for the 
\*(xT".
.P
Included in this release is a version of the
"Test Environment Toolkit"
.SM ( TET ).
This is required to build and execute the \*(xT.
The "Test Environment Toolkit" 
is a software tool developed by X/Open,
UNIX International,
and the Open Software Foundation.
More details of the \s-1TET\s0 appear in appendix E.
.P
The contents of this document cover the installation and use of the included 
version of the \s-1TET\s0.
.SK
.H 1 "Preparation"
This section of the User Guide describes how to check that the system on which 
you want to build the \*(xT has the required utilities and sufficient 
disc space, how to check the version of the \*(xW\*F
.FS
The \*(xW is a trademark of the Massachusetts Institute of Technology.
.br
\*(xW Version\ 11 Release\ 4 is abbreviated to X11R4 in this document.
.br
\*(xW Version\ 11 Release\ 5 is abbreviated to X11R5 in this document.
.FE
you wish to test,
and how to extract the software from the supplied distribution media.
.H 2 "Utilities"
The \*(xT assumes that the following utilities are available on your system.
.H 3 "Bourne shell"
The configuration and building stages include example instructions which 
have only been tested using the Bourne shell.
.P
The build configuration file sets the SHELL variable so that the Bourne 
shell will be used by \fCmake\fP. No other settings for this variable 
have been tested.
.H 3 "make"
The building stages assume the existence of \fCmake\fP.
.H 3 "awk"
The report writer \fCrpt\fP uses \fCawk\fP.
.H 3 "Compiler"
A C compiler and link editor are required. The \*(xT assumes that when these 
utilities execute successfully, they return a value of zero.
The names of these utilities may be set in build
configuration parameters.
.H 3 "Library archiver"
A library archiver and a means of ordering the libraries are required.
The ordering software may be part of the library archiver, the 
\fCranlib\fP utility, or the utilities \fClorder\fP and \fCtsort\fP.
The names of these utilities may be set in build
configuration parameters.
.H 3 "File utilities"
The \*(xT uses utilities to copy, move, remove and link files during
the build stages. 
The names of these utilities may be set in build
configuration parameters.
.H 2 "Checking your version of the \*(xW"
If your version of the \*(xW supports the 
.SM XTEST
extension, you will
be able to perform tests for 
some assertions which are otherwise untestable. The
.SM XTEST
extension has been produced by MIT since the initial release of X11R5,
based on a specification\*F
.FS
Drake, K.J.,
\(lqSome Proposals for a Minimal X11 Testing Extension.\(rq
.I
UniSoft Ltd. June 1991
.FE
produced by UniSoft.
The extension provides access to the X server to enable
testing of the following areas of the \*(xW:
.DL
.LI
Those which rely on the simulation of device events.
.LI
Those requiring access to opaque client side data structures.
.LI
Those requiring information on the cursor attribute of windows.
.LE
.P
Before you configure the \*(xT, you should determine whether your 
version of the \*(xW includes the 
.SM XTEST
extension, and, if so, whether 
you wish to configure and build the \*(xT to enable these features to 
be tested.
.P
There are two things to check:
.AL
.LI
Check whether your X server supports the 
.SM XTEST
extension.
This can be done by printing the list of extensions available in your 
X server using the X utility
.C xdpyinfo .
Note - the name of the 
extension should be printed exactly as in this User Guide - 
there are other testing extensions for X which are not compatible 
with the 
.SM XTEST
extension.
.LI
Check whether you have the required libraries to link the test suite clients
so as to access the 
.SM XTEST
extension. All test suite clients must be linked with Xlib, which is 
normally named 
.C libX11.a .
If you want to access the 
.SM XTEST
extension, 
you will need two further libraries. These are the 
.SM XTEST 
library (normally named
.C libXtst.a )
and the X extension library (normally named
.C libXext.a ).
.LE
.H 2 "Installing the \*(xT"
Change to the directory in which you wish to install the distribution.
Set an environment variable \s-1TET_ROOT\s0 to the full path name of
that directory.
.P
Load the software from the media supplied into that directory.
The precise commands you should use depend on the format of the media
supplied to you, the utilities available on your system, 
the options
supported by the utilities, and 
the names of 
the tape devices on your system.
See the Release Notes for more information about installation.
.P
.SK
.H 1 "Configuring the \*(xT"
This section contains instructions on all the procedures you should 
go through in order to configure the \*(xT, before attempting to 
build it. 
.P
There is a description of the \s-1TET\s0 build tool in section 3.1, and the 
relationship between the \s-1TET\s0 build scheme and the Imake scheme in 
section 3.2.
.P
Sections 3.3 and 3.4 contain details of build and clean 
configuration parameters, which you
should edit to reflect the configuration of the target platform on which 
the \*(xT is to be built.
.P
Section 3.5 contains details of source files and include files 
which contain system dependent 
data which cannot be specified via the build configuration parameters.
You should check these files before configuration and if necessary edit
them to be suitable for your system.
.H 2 "The \s-1TET\s0 build tool"
The \s-1TET\s0 provides a scheme to execute a build tool, which builds
the tests in the \*(xT.
The execution of the build tool in the 
\s-1TET\s0
is controlled by a small number of 
\s-1TET\s0
configuration parameters, contained in a build configuration file. These
are described in section 3.3.1.
.P
A build tool has been developed and is provided as part of the \*(xT. 
This is a shell script named \fCpmake\fP, which is supplied in the directory
\fC$TET_ROOT/xtest/bin\fP. The shell script \fCpmake\fP is an interface to the 
\fCmake\fP system command, and when invoked from the 
\s-1TET\s0
it builds a test using the rules provided in a
\fCMakefile\fP.
.P
Each \fCMakefile\fP in the \*(xT
is written portably, using symbolic names to describe commands and 
parameters which may vary from system to system. The values of these
symbolic names are all obtained by \fCpmake\fP from additional parameters in
the build configuration file
which are described in sections 3.3.2-3.3.7.
.P
The \fCpmake\fP utility may be invoked directly from the shell,
as well as via the \s-1TET\s0, to build individual parts of the 
\*(xT. This is described further in subsequent sections of this guide.
.P
There is also a clean tool \fCpclean\fP which is
an interface to the system \fCmake clean\fP system command. This 
uses parameters in a clean configuration file. 
.H 2 "Relationship between \s-1TET\s0 build scheme and Imake"
The \s-1TET\s0 is designed to provide a simple and self contained
interface to configure and build tests. The \*(xT can be configured and
built with no specialised knowledge of the \*(xW beyond 
that contained in the \*(xT documentation, and using a limited set of commonly
available system commands. The only information required to configure and 
build the \*(xT is the location of the \*(xW Xlib and include files.
.P
The \*(xW itself includes a
configuration scheme which is known as \fCImake\fP.
This uses a utility \fCimake\fP supplied as part of the \*(xW 
to create \fCMakefiles\fP from portable 
description files called \fCImakefiles\fP.
.P
If you are familiar with the \fCImake\fP scheme, and have used it to configure 
and build
the \*(xW on the platform being used to build the \*(xT, you may be able 
to set a limited number of the \s-1TET\s0 build configuration variables 
described in section 3.3 to the same value you used for 
an \fCImake\fP variable. Where this 
is possible, the name of the corresponding \fCImake\fP variable is cross 
referenced.
.H 2 "Build configuration parameters"
All build configuration parameters are contained in 
a configuration file that forms part of the \s-1TET\s0.
This file should be edited to reflect the configuration of the target machine.
The file
.cS
$TET_ROOT/xtest/tetbuild.cfg
.cE
contains all the parameters that are needed to build the \*(xT.
The parameters are grouped in seven sections within the configuration file.
.H 3 "Configuration Parameters defined by the \s-1TET\s0"
None of these parameters require changing. They are already set to 
defaults which are correct for the \*(xT.
.P
.VL 15 0
.LI \s-1TET_BUILD_TOOL\s0
.br
The name of the program that the
.SM TET
will execute in build mode.
.P
You should use the \fCpmake\fP command that is supplied
in the directory \fC$TET_ROOT/xtest/bin\fP.
.cS
Eg: TET_BUILD_TOOL=pmake
.cE
.LI \s-1TET_BUILD_FILE\s0
.br
Any flags required by the build tool.
This parameter should be empty.
.cS
Eg: TET_BUILD_FILE=
.cE
.LI \s-1TET_CLEAN_TOOL\s0
.br
The name of the program that the
.SM TET
will execute in clean mode.
.P
You should use the \fCpclean\fP command that is supplied
in the directory \fC$TET_ROOT/xtest/bin\fP.
.cS
Eg: TET_CLEAN_TOOL=pclean
.cE
.LI \s-1TET_CLEAN_FILE\s0
.br
Any flags required by the clean tool. 
This parameter should be empty.
.cS
Eg: TET_CLEAN_FILE=
.cE
.LI \s-1TET_OUTPUT_CAPTURE\s0
.br
This flag is used by the \s-1TET\s0 to enable the output from the build tool 
to be saved and copied into the journal file. This line should not be 
altered.
.LE
.H 3 "Configuration for system commands"
In this section the names of system commands are specified.
.VL 15 0
.LI \s-1SHELL\s0
The following line should cause the Bourne shell to be used 
by make.
.cS
Eg: SHELL=/bin/sh
.cE
.LI \s-1CC\s0
A command to invoke the C compiler.
.cS
Eg: CC=cc
.cE
.P
\fIImake variable: CcCmd\fP
.LI \s-1RM\s0
A command to remove a file without interactive help.
.cS
Eg: RM=rm -f
.cE
.P
\fIImake variable: RmCmd\fP
.LI \s-1AR\s0
A command to generate a library archive.
.cS
Eg: AR=ar crv
.cE
.P
\fIImake variable: ArCmd\fP
.LI \s-1LD\s0
A command to link object files.
.cS
Eg: LD=ld
.cE
.P
\fIImake variable: LdCmd\fP
.LI \s-1LN\s0
A command to make hard links.
.cS
Eg: LN=ln
.cE
.P
\fINB: This does not correspond to the Imake variable: LnCmd\fP
.LI \s-1RANLIB\s0
If the system supports a command to order library 
archives into random access libraries, then set the parameter to that command.
Otherwise it should be set to \fCecho\fP (or a command that does nothing).
.cS
Eg: RANLIB=ranlib
.cE
.P
\fIImake variable: RanlibCmd\fP
.LI \s-1TSORT\s0
Set to \fCcat\fP if AR was set to a command which inserts a symbol table
in the library archive,
or if RANLIB was set to a command which creates a random access library,
otherwise set to \fCtsort\fP.
.LI \s-1LORDER\s0
Set to \fCecho\fP if AR was set to a command which inserts a symbol table
in the library archive,
or if RANLIB was set to a command which creates a random access library.
otherwise set to \fClorder\fP.
.LI \s-1CP\s0
A command to copy files.
.cS
Eg: CP=cp
.cE
.P
\fIImake variable: CpCmd\fP
.LI \s-1CODEMAKER\s0
A utility to produce C source files from dot-m files.
The supplied utility \fCmc\fP should always be used.
This line should not be altered.
.cS
Eg: CODEMAKER=mc
.cE
.LE
.H 3 "Configuration for the \s-1TET\s0"
This section contains the locations of various parts of the \s-1TET\s0.
Usually only the first four parameters will need changing,
unless files have been moved from their default locations.
.VL 15 0
.LI \s-1TET_ROOT\s0
The directory that contains all the files in the \*(xT.
This should be set to the path to which \fCTET_ROOT\fP was set (see the
section entitled "Installing the \*(xT").
It must be written out as a full path without using any variable notation.
.LI \s-1TETBASE\s0
The directory that contains all the files in the \s-1TET\s0 system.
This is used for convenience in defining the other directories.
This should be set to \fC${TET_ROOT}/tet\fP.
.LI \s-1PORTINC\s0
An option that can be given to the C compiler
that will cause it to search all directories that are
required to allow portability to systems that do not support
.SM POSIX .
Should be empty for
.SM POSIX
systems.
If compiling on a \s-1BSD\s0 system using the supplied compatibility library,
then the following line should be used.
(See section entitled "The portability library").
.cS
Eg: PORTINC=-I${TET_ROOT}/port/INC
.cE
.LI \s-1PORTLIB\s0
A library containing
.SM POSIX.1
and C library functions that
are not supplied by the system.
This should be empty for a
.SM POSIX
system.
If compiling on a \s-1BSD\s0 system using the supplied compatibility library,
then the following line should be used.
(See section entitled "The portability library").
.cS
Eg: PORTLIB=${TET_ROOT}/port/libport.a
.cE
.LI \s-1TETINCDIR\s0
The directory containing the
.SM TET
headers.
.cS
Eg: TETINCDIR=${TETBASE}/inc/posix_c
.cE
.LI \s-1TETLIB\s0
The directory containing the 
.SM TET
library.
.cS
Eg: TETLIB=${TETBASE}/lib/posix_c
.cE
.LI \s-1TCM\s0
The Test Control Manager.
This is part of the \s-1TET\s0.
It is an object file that is linked with each test.
.cS
Eg: TCM=${TETLIB}/tcm.o
.cE
.LI \s-1TCMCHILD\s0
The Test Control Manager.
This is part of the \s-1TET\s0.
It is an object file that is linked with each program that is 
executed within a test by tet_exec().
.cS
Eg: TCMCHILD=${TETLIB}/tcmchild.o
.cE
.LI \s-1APILIB\s0
The \s-1TET\s0 \s-1API\s0 library.
.cS
Eg: APILIB=${TETLIB}/libapi.a
.cE
.LE
.H 3 "Configuration parameters for the \*(xT"
Only the first two of these parameters require changing unless
directories have been moved from their default locations.
.VL 15 0
.LI \s-1XTESTHOST\s0
The name of the host on which test suite clients are to be executed.
This may be set to the value returned by a command which can be executed
using the PATH you have set on your host, or may be set to a specific name.
This is used to produce a resource file named .Xdefaults-$(\s-1XTESTHOST\s0)
in the test execution directory.
The resource file is created when building the test for XGetDefault.
This parameter is only used in the Makefile of the test for XGetDefault.
.cS
Eg. XTESTHOST=`hostname`
Eg. XTESTHOST=`uname -n`
Eg. XTESTHOST=triton
.cE
.LI \s-1XTESTFONTDIR\s0
The directory in which to install the test fonts.
.cS
Eg: XTESTFONTDIR=/usr/lib/X11/fonts/xtest
.cE
.LI \s-1XTESTROOT\s0
The directory that is the root of the \*(xT.
.cS
Eg: XTESTROOT=${TET_ROOT}/xtest
.cE
.LI \s-1XTESTLIBDIR\s0
The directory containing libraries for the \*(xT.
.cS
Eg: XTESTLIBDIR=${XTESTROOT}/lib
.cE
.LI \s-1XTESTLIB\s0
The xtest library.
This library contains
subroutines that are common to many tests in the \*(xT.
.cS
Eg: XTESTLIB=${XTESTLIBDIR}/libxtest.a
.cE
.LI \s-1XSTLIB\s0
The X Protocol test library.
This library contains
subroutines that are common to many tests in the X Protocol section 
of the \*(xT.
.cS
Eg: XSTLIB=${XTESTLIBDIR}/libXst.a
.cE
.LI \s-1XTESTFONTLIB\s0
The fonts library.
This library contains
font descriptions that are common to many tests in the \*(xT.
.cS
Eg: XTESTFONTLIB=${XTESTLIBDIR}/libfont.a
.cE
.LI \s-1XTESTINCDIR\s0
The xtest header file directory.
This directory contains headers that are local to the \*(xT.
.cS
Eg: XTESTINCDIR=${XTESTROOT}/include
.cE
.LI \s-1XTESTBIN\s0
The xtest binary file directory.
This directory contains utility programs that are used by \*(xT.
.cS
Eg: XTESTBIN=${XTESTROOT}/bin
.cE
.LE
.H 3 "System Parameters"
Location of system libraries and include files.
.VL 15 0
.LI \s-1SYSLIBS\s0
Options to cause the C compiler to search
any system libraries that are required for the \*(xT
that are not searched by default.
This will probably include Xlib.
.cS
Eg: SYSLIBS=-lX11
.cE
If you wish to build the \*(xT to make use of the 
.SM XTEST
extension, you
will need to include the 
.SM XTEST
library and the X\ extension library (in that order).
.cS
Eg: SYSLIBS=-lXtst -lXext -lX11
.cE
.P
\fIImake variables: ExtraLibraries\fP
.LI \s-1XP_SYSLIBS\s0
Any system libraries that are needed, to link the
X Protocol tests. This will include Xlib, since libXst.a
(which is part of the test suite) will include at least one call to
XOpenDisplay.
.cS
Eg: XP_SYSLIBS=-lX11
.cE
.P
\fIImake variables: ExtraLibraries\fP
.LI \s-1SYSINC\s0
Any commands that should be given to the C compiler
to cause all relevant system include files to be included.  This will
probably
include /usr/include/X11.
.cS
Eg: SYSINC=-I/usr/include/X11
.cE
.LE
.H 3 "C Compiler Directives"
Directives to the C compiler.
Usually only the first four parameters will need changing. The
remainder are internally used parameters, which are an amalgam of previously
set parameters.
.VL 15 0
.LI \s-1COPTS\s0
Options to the C compiler.
.cS
Eg: COPTS=-O
.cE
.P
\fIImake variables: DefaultCDebugFlags and DefaultCCOptions\fP
.LI \s-1DEFINES\s0
Options required by the C compiler to set up any required defines.
For example in strict
.SM ANSI
Standard-C systems you will need to define
.SM _POSIX_SOURCE .
Additionally on an
.SM X/Open
conformant system it may be necessary to define
.SM _XOPEN_SOURCE .
.cS
Eg: DEFINES=-D_POSIX_SOURCE
.cE
.P
If there is no symbol
.C NSIG
defined in the system header file 
\fCsignal.h\fP, then this has to be supplied for
use by the \s-1TET\s0 \s-1API\s0.
It should be the number of signal types on the system.
.cS
Eg: DEFINES=-D_POSIX_SOURCE -DNSIG=32
.cE
If you wish to build the \*(xT to make use of the 
.SM XTEST
extension, you
will need to define 
.SM XTESTEXTENSION .
.br
.SM XTESTEXTENSION
is only used when building the \*(xT library.
.cS
Eg: DEFINES=-D_POSIX_SOURCE -DNSIG=32 -DXTESTEXTENSION
.cE
.P
\fIImake variables: StandardDefines\fP
.LI \s-1XP_DEFINES\s0
C compiler defines specific to the X Protocol tests.
.br
This can be set as DEFINES, but
you can build support for additional connection methods beyond TCP/IP,
using the following defines, if XP_OPEN_DIS is
XlibNoXtst.c (R4/R5 XOpenDisplay emulation):
.cS
-DDNETCONN - Connections can also use DECnet\*F.
-DUNIXCONN - Connections can also use UNIX\*F domain sockets.
.cE
.br
Refer to your documentation for building and installing Xlib on
your platform.
.FS
DEC and DECnet are registered trademarks of Digital
Equipment Corporation.
.FE
.FS
UNIX is a registered trademark of UNIX System Laboratories, Inc. in
the U.S. and other countries.
.FE
.br
If XP_OPEN_DIS is one of XlibXtst.c or XlibOpaque.c then none of
the defines listed above will be required.
.cS
Eg: XP_DEFINES=-D_POSIX_SOURCE -DUNIXCONN
.cE
.P
\fIImake variables: StandardDefines\fP
.LI \s-1LINKOBJOPTS\s0
Options to give to the LD program to link object
files together into one object file that can be further linked.
.cS
Eg: LINKOBJOPTS=-r
.cE
.LI \s-1INCLUDES\s0
Options to cause C compiler to search the correct directories
for headers.
This should not need changing as it is just an amalgam of
other parameters.
.cS
.ps -2
INCLUDES=-I. ${PORTINC} -I${TETINCDIR} -I${XTESTINCDIR} ${SYSINC}
.ps +2
.cE
.LI \s-1CFLAGS\s0
Flags for the C compiler.
This should not need changing as it is just an amalgam of other
parameters.
Note that \fC\s-1CFLOCAL\s0\fP is not defined in the configuration file;
it is available for use in makefiles, to define
parameters that only apply to a particular case.
(It intentionally uses parentheses rather than braces)
.cS
.ps -2
CFLAGS=$(CFLOCAL) $(COPTS) $(INCLUDES) $(DEFINES)
.ps +2
.cE
.LI \s-1XP_CFLAGS\s0
Flags for the C compiler.
This parameter is used by the \*(xP in the \*(xT.
This should not need changing as it is just an amalgam of other
parameters.
.cS
.ps -2
XP_CFLAGS=$(CFLOCAL) $(COPTS) $(INCLUDES) $(XP_DEFINES)
.ps +2
.cE
.LI \s-1LDFLAGS\s0
Flags used by the loader.
This is needed on some systems 
to specify options used when object files are linked to produce an executable.
.cS
.ps -2
Eg. LDFLAGS=-ZP
.ps +2
.cE
.LI \s-1LIBS\s0
List of libraries.
This should not need changing as it is just an amalgam of other
parameters.
.cS
.ps -2
LIBS=${XTESTLIB} ${XTESTFONTLIB} ${APILIB} ${PORTLIB}
.ps +2
.cE
.LI \s-1XP_LIBS\s0
List of libraries.
This parameter is used by the \*(xP in the \*(xT.
This should not need changing as it is just an amalgam of other
parameters.
.cS
.ps -2
XP_LIBS=${XSTLIB} ${XTESTLIB} ${XTESTFONTLIB} ${APILIB} ${PORTLIB}
.ps +2
.cE
.LI \s-1XP_OPEN_DIS\s0
A choice of which code to build in the X Protocol library 
to make an X server connection.
This must be set to one of three possible values:
.VL 4 0
.LI XlibXtst.c
.br
Use this option only if your Xlib includes post R5 enhancements 
to _XConnectDisplay 
ensuring maximum portable protocol test coverage. These enhancements include
arguments to _XConnectDisplay to return authorisation details on 
connection. If you use this option when your Xlib does not have these 
enhancements to _XConnectDisplay, the results of running the \*(xP 
will be 
.B undefined .
.LI XlibOpaque.c	
.br
You have a normal R4 Xlib or early R5 Xlib which you 
cannot patch to include the enhancements to 
_XConnectDisplay, and you cannot emulate these by 
building XlibNoXtst.c, so only client-native testing 
can be done portably, and no failure testing of 
XOpenDisplay can be done.
This option uses XOpenDisplay to make the connection, 
from which the file descriptor is recovered for our own use. 
XCloseDisplay shuts down the connection.
.LI XlibNoXtst.c	
.br
As for XlibOpaque.c but you can use the R4/R5 
connection emulation supplied. (Note: R4/R5 independent)
This will ensure maximum protocol test coverage
but may not be portable to all platforms.
.LE
.P
Reasons for not being able to build XlibNoXtst.c might include:
.br
i)  different interfaces to connection setup and connection read/write;
.br
ii) different access control mechanisms.
.br
Refer to your Xlib documentation for further details.
.cS
Eg. XP_OPEN_DIS=XlibOpaque.c
.cE
.LE
.H 3 "Pixel validation section"
This section defines a number of parameters that are used only when
generating known good image files. These are not intended to be modified 
and need not be used when running the test suite.
They are only used in the development environment
at UniSoft when generating known good image files.
.H 2 "Clean configuration parameters"
The \s-1TET\s0 provides a scheme to execute a clean tool, which removes
previously built tests and object files.
.P
All clean configuration parameters are contained in a configuration file that
forms part of the \s-1TET\s0.
The file
.cS
$TET_ROOT/xtest/tetclean.cfg
.cE
contains all the parameters that are needed to clean the \*(xT.
.P
To save configuration effort, 
we have arranged that the build and clean configuration files
may contain identical parameter settings. Both files are needed,
since the 
.SM TET
requires both a default build and clean configuration file.
.P
Copy the build configuration file into the clean configuration file:
.cS
cd $TET_ROOT/xtest
cp tetbuild.cfg tetclean.cfg
.cE
.H 2 "System dependent source files"
This section describes source files and include files provided 
in the \*(xT which contain data,
which you may need to edit to reflect the system under test.
.H 3 "Host address structures"
The file \fCxthost.c\fP
in the directory \fC$TET_ROOT/xtest/src/lib\fP
contains three items, which you may need to edit to reflect the system 
under test. These are all related to the mechanisms provided by the X
server under test to add, get or remove hosts from the access control list.
These are only used in the tests
for those Xlib functions which use or modify the access control list.
.P
The host access control functions use the XHostAddress structure.  You
should refer to the Xlib documentation for your system, to determine
the allowed formats for host addresses in an XHostAddress structure.
You may also find it helpful to refer to the X Window System Protocol
documentation supplied with the X server under test. The section
describing the ChangeHosts protocol request gives examples of host
address formats supported by many X servers.  The symbols FamilyInternet,
FamilyDECnet, FamilyChaos and FamilyUname are defined on many systems
in the include files X.h and Xstreams.h. The X server under test is not
guaranteed to support these families, and may support families not
listed here. You should find out which families are supported for the X
server under test, by examining the header files supplied with your
system, and consulting the documentation supplied with the X server.
.P
Some default declarations are contained in the file, but there is no 
guarantee that they will work correctly on your system.
.P
The three items are as follows:
.AL
.LI
You should ensure that there is a declaration for an
array xthosts[] of at least 5 XHostAddress structures containing
valid family,length,address triples.
.LI
You should ensure that there is a declaration for an
array xtbadhosts[] of at least 5 XHostAddress structures containing
invalid family,length,address triples.
You should ensure that there is a declaration for an array
xtbadhosts[] of at least 5 XHostAddress structures containing invalid
family,length,address triples. If you cannot use the supplied examples,
the simplest way to do this is to use an invalid family, which is not
supported by the X server under test, in each structure of the array.
.LI
You should ensure that there is a declaration for a
function samehost() that compares two XHostAddress structures
and returns True if they are equivalent. (It is unlikely that the sample 
function will need modification - no systems requiring modification have 
yet been identified).
.LE
.SK
.H 1 "Building the \s-1TET\s0"
The \*(xT
runs under the 
Test Environment Toolkit
(\s-1TET\s0).
.P
This section of the User Guide tells you how to build and install the 
supplied version of the
.SM TET .
.P
The following instructions assume the use of a Bourne shell.
.P
The \s-1PATH\s0 variable should have the directory \fC$TET_ROOT/xtest/bin\fP
prepended to it.
.cS
PATH=$TET_ROOT/xtest/bin:$PATH
export PATH
.cE
.H 2 "The portability library"
The current version of the \s-1TET\s0 used by the \*(xT
is designed to run on a
\s-1POSIX.1\s0
system.
.P
Since many systems running the \*(xW
currently run on \s-1BSD\s0 based systems a portability library
that emulates the required routines using \s-1BSD\s0 facilities has
been provided.
.P
This library is not part of the \s-1TET\s0 itself.
.P
The portability library source is kept in \fC$TET_ROOT/port\fP.
.P
The portability library may be useful in porting the \*(xT to other
environments as described below.
Please refer to the "Release Notes for the \*(xT"
for details of the target execution environments, 
and a list of systems to which it has already been ported.
.H 3 "Porting to a POSIX.1 system"
If your system conforms to
.SM POSIX.1
and has an
.SM ANSI
Standard-C compiler then this library should not be built
and so this section can be skipped.
The exception is that \fCputenv()\fP may not exist on a
\s-1POSIX.1\s0\*F
.FS
IEEE Std 1003.1-1990, \fIPortable Operating System Interface for
Computer Environments\fR
.FE
system, however it is in the
\s-1SVID\s0\*F
.FS
System V Interface Definition, Issue 1, AT&T, Spring 1985.
.FE
and the
\s-1XPG\s0\*F,
.FS
\fIX/Open Portability Guide Issue 3, Volume 2: XSI System Interface and Headers\fR
.FE
so in practice most
.SM non- BSD
machines will have this function.
.H 3 "Porting to a BSD system"
If the system is a standard \s-1BSD\s0 one,
then the portability library can be used as it is; build
it as follows.
.cS
cd $TET_ROOT/port
pmake
.cE
.H 3 "Porting to other systems"
The portability
library may be useful as a base for porting the \s-1TET\s0 to other
.SM non- POSIX
systems,
however the portability library is designed to run on a \s-1BSD\s0 system,
and will not necessarily build without change on other systems.
.P
The following routines are emulated for use under a \s-1BSD\s0 system,
and these may be needed on other systems:
.cS
getcwd() getopt() putenv() sigaction()
sigaddset() sigdelset() sigemptyset() sigfillset()
sigismember() sigpending() sigprocmask() sigsuspend()
strchr() strcspn() strftime() strpbrk() strrchr()
strspn() strtok() toupper() upcase()
vsprintf() waitpid() 
.cE
Only the features that are used by the \*(xT are emulated.
They are not meant to mimic completely the standard behaviour.
.P
There is also an include directory 
.C $TET_ROOT/port/INC
that contains header files
that are required that are not found on a \s-1BSD\s0 system.
These files contain only items that are needed for the \*(xT,
they are not designed to replace completely the standard ones.
.P
To adapt the portability library to other systems, 
the following hints may be found useful:
.BL
.LI
Examine the directory 
.C $TET_ROOT/port/INC .
If the system already provides a standard conforming header file
of the same name
as one in the \s-1INC\s0 directory, then remove the version
from the \s-1INC\s0 directory.
.LI
The header files contain the bare minimum required to compile the
\*(xT, and use \s-1BSD\s0 features.
It may be necessary to alter them to suit the local system.
This applies particularly to
.C signal.h .
.LI
It may be necessary to add other header files.
.LI
In the library \fCMakefile\fP remove any function that is already provided by
the system in a standard conforming form.
.LI
Examine the code of the remaining functions to make
sure that they will work on the target system.
.LE
.P
.H 2 "Building libraries and utilities"
There is a top level Makefile which can be used to automatically perform 
a number of the following steps. You should still check through the User Guide
and perform the steps which need to be done manually. In particular you
need to build
and install the test fonts as described in the section entitled 
"Compiling and installing the test fonts".
.P
The top level Makefile enables the following steps to be performed:
.P
Building the \s-1TET\s0:
.AL
.LI
The Test Case Controller (TCC)
.LI
The API library
.LE
.P
Building the X test suite libraries and utilities:
.AL
.LI
Building the X test suite library
.LI
Building the X Protocol library
.LI
Building the X test fonts library
.LI
Building the mc utility
.LI
Building the blowup utility
.LE
.P
To use the top level Makefile, move to the top level directory:
.cS
cd $TET_ROOT
.cE
.P
Make the utilities and libraries with the command:
.cS
make
.cE
.H 2 "The Test Case Controller (TCC)"
Move to the directory containing the \s-1TCC\s0 source.
.cS
cd $TET_ROOT/tet/src/posix_c/tools
.cE
.P
Make the
.SM TCC
with the command:
.cS
pmake install
.cE
.P
Note: the supplied version of the \s-1TCC\s0 
assumes that the \fIcp\fP utility on your system supports recursive 
copy using the option \fI-r\fP.  There are two occurrences of \fIcp\fP in
the file \fCexec.c\fP which use this option.
.P
In the \*(xT, recursive copying is not required.
.P
If your system does not support this option, you can remove the use of 
this option in the source code 
before building the \s-1TCC\s0. If you do this you may 
not be able to use the supplied \s-1TCC\s0 with other test suites.
.P
Alternatively, you can provide a shell script in the directory 
\fC$TET_ROOT/xtest/bin\fP
which copies files using \fIcp\fP but ignores any option \fI-r\fP.
.H 2 "The \s-1API\s0 library"
Move to the 
.SM API
library source directory.
.cS
cd $TET_ROOT/tet/src/posix_c/api
.cE
.P
Run the command
.cS
pmake install
.cE
which should produce the files \fClibapi.a\fP and the Test
Case Manager files \fCtcm.o\fP and \fCtcmchild.o\fP.
.H 1 "Building the X test suite libraries and utilities"
.H 2 "The X test suite library"
A library of common subroutines for the \*(xT
has source in \fC$TET_ROOT/xtest/src/lib\fP.
This is built automatically when building tests in the \*(xT.
Should it be required to build it separately for any reason
run the command.
.cS
cd $TET_ROOT/xtest/src/lib
pmake install
.cE
.P
The list of source files in this library is described in the 
"Programmers Guide".
.H 2 "The X Protocol library"
A library of common subroutines for the \*(xP in the \*(xT
has source in \fC$TET_ROOT/xtest/src/libproto\fP.
This is built automatically when building tests in the \*(xT.
Should it be required to build it separately for any reason
run the command.
.cS
cd $TET_ROOT/xtest/src/libproto
pmake install
.cE
.P
The list of source files in this library is described in the 
"Programmers Guide".
.H 2 "The X test fonts library"
A library of common subroutines defining the 
characteristics of the test fonts for the \*(xT
has source in \fC$TET_ROOT/xtest/fonts\fP.
This is built automatically when building tests in the \*(xT.
Should it be required to build it separately for any reason
run the command.
.cS
cd $TET_ROOT/xtest/fonts
pmake install
.cE
.P
The list of source files in this library is described in the 
"Programmers Guide".
.P
Note that the directory 
\fC$TET_ROOT/xtest/fonts\fP also contains the test fonts themselves in
bdf format, which must be compiled and installed. Instructions for 
performing these steps are included in the next section entitled
"Compiling and installing the test fonts".
.H 2 "Compiling and installing the test fonts"
The \*(xT contains a series of test fonts which are used 
to test the correctness of the information returned by the graphics 
functions in the \*(xW. This is done by comparing the information
returned by those functions with the expected font characteristics 
which are compiled into the tests via the X test fonts library.
The X test fonts library is described in an earlier section of this document.
.P
There are seven test fonts whose descriptions are contained in the files
.cS
xtfont0.bdf	xtfont1.bdf	xtfont2.bdf
xtfont3.bdf	xtfont4.bdf	xtfont5.bdf
xtfont6.bdf
.cE
.P
These files are located in the directory \fC$TET_ROOT/xtest/fonts\fP.
.P
The manner in which fonts should be compiled and installed for any 
particular X server is system dependent, and you should refer to 
the instructions supplied with your release of the \*(xW for 
details of how to do this.
.P
Some sample instructions are given here which may be useful on many 
systems. These may not be appropriate for your system, or they may 
need adaptation to work properly on your system and so are provided 
only as a guide.
.AL
.LI
Move to the directory \fC$TET_ROOT/xtest/fonts\fP.
.cS
cd $TET_ROOT/xtest/fonts
.cE
.LI
Compile the seven \fCbdf\fP files into \fCsnf\fP, \fCpcf\fP, or \fCfb\fP
format, as appropriate for your system.
.cS
pmake comp_snf
.cE
or
.cS
pmake comp_pcf
.cE
or
.cS
pmake comp_dxpcf
.cE
or
.cS
pmake comp_fb
.cE
.LI
Copy the compiled fonts into the server font directory
(the \fCXTESTFONTDIR\fP configuration parameter).
.cS
pmake install_snf
.cE
or
.cS
pmake install_pcf
.cE
or
.cS
pmake install_dxpcf
.cE
or
.cS
pmake install_fb
.cE
.LE
.H 2 "Building the \fCmc\fP utility"
The 
.C mc 
utility is used to generate test set source files and Makefiles
from a template file, known as a dot-m file. 
The file naming scheme is described further in appendix B.
The file formats are described further in the "Programmers Guide".
.P
The Makefiles and test set source files will be created using 
.C mc 
whenever test sets are built, if the dot-m file is found to be 
newer than the source file or Makefile, or if these files do not 
exist.
.P
Build 
.C mc 
and install in the xtest bin directory as follows.
.cS
cd $TET_ROOT/xtest/src/bin/mc
pmake install
cd $TET_ROOT/xtest/src/bin/mc/tmpl
pmake install
.cE
.H 2 "Building the blowup utility"
The blowup utility is required for examining any incorrect image files 
generated by the X server during a test run. Instructions for running the
blowup program are given in the section entitled "Examining image files".
.P
Build 
.C blowup 
and install in the xtest bin directory as follows.
.cS
cd $TET_ROOT/xtest/src/pixval/blowup
pmake install
.cE
.SK
.H 1 "Building the tests"
.H 2 "Building tests using the \s-1TET\s0"
The entire \*(xT can be built by using the 
build mode of the \s-1TCC\s0. In this mode, the build configuration
parameters in the file 
.C $TET_ROOT/xtest/tetbuild.cfg 
are used to build each test 
set in the \*(xT separately.
.P
.cS
cd $TET_ROOT/xtest
tcc -b [ -s scenario_file ]  [ -j journal_file ] [ -y string ] xtest all
.cE
.VL 5 0
.LI \fC-b\fP
.br
This invokes the \s-1TCC\s0 in build mode.
(If you have just finished building the \s-1TCC\s0 from the \fCcsh\fP,
you will probably have to \fCrehash\fP to get \fCtcc\fP in your path.)
.LI "\fC-s scenario_file\fP"
.br
This option builds the test sets in the named scenario file.
The default is a file named \fCtet_scen\fP in the directory 
\fC$TET_ROOT/xtest\fP.
For more details refer to the section entitled 
"Building modified scenarios using the \s-1TET\s0".
.LI "\fC-j journal_file\fP"
.br
This option sends the output of the build to the named journal file.
The default is a file named \fCjournal\fP in a newly created sub-directory 
of \fC$TET_ROOT/xtest/results\fP. Sub-directories are created with sequential
four digit numbers, with the 
.SM TCC
flags (in this case "b") appended.
The \s-1TCC\s0 will exit if the specified journal file already exists, thus the
journal file should be renamed or removed
before attempting to execute the \s-1TCC\s0.
.LI "\fC-y string\fP"
.br
This option only builds tests which include the specified string in the 
scenario file line. This may be used to build specific sections or individual
test sets.
.LI \fCxtest\fP
.br
This is the name of the test suite.
It determines the directory under $\s-1TET_ROOT\s0
where the test suite is to be found.
.LI \fCall\fP
.br
This is the scenario name in the default scenario file
\fC$TET_ROOT/xtest/tet_scen\fP.
For more details refer to the section entitled 
"Building modified scenarios using the \s-1TET\s0"
.LE
.P
This will execute the \s-1TET\s0 build tool in the \s-1TET\s0 configuration 
variable 
.SM TET_BUILD_TOOL 
(which is normally pmake),
in each test set directory of the \*(xT.
.P
The journal file should be examined to verify
that the build process succeeded.
The report writer \fCrpt\fP cannot interpret the contents 
of a journal file produced during the build process.
.P
Note: If the \s-1TCC\s0
terminates due to receipt of a signal which 
cannot be caught, the \s-1TCC\s0
may leave lock files in the test source directories. Subsequent 
attempts to restart the \s-1TCC\s0 may give error messages 
saying that a lock file was encountered. At this point 
\s-1TCC\s0
may suspend the build. It may be 
necessary to find and remove files or directories named \fCtet_lock\fP 
before continuing.
.H 3 "Signal handling in the \s-1TET\s0"
An interrupt signal (caused for example by typing the 
system interrupt character on the controlling terminal)
will cause the \s-1TCC\s0 to abort the currently executing test case. The 
journal file output records the fact that the test case was interrupted.
.P
Any other signal which can be caught by the \s-1TCC\s0 causes it to terminate.
By default, the system suspend character will also cause the \s-1TCC\s0
to terminate. If you wish to be able to suspend the \s-1TCC\s0, 
you can add the relevant signals to the parameter SIG_LEAVE
in the Makefile for the \s-1TCC\s0. 
Signals in this list will not be caught, but will cause their
default action.
This is explained further in the Test Environment Tookit Release Notes.
.H 2 "Building, executing and cleaning tests using the \s-1TET\s0"
Each test in the \*(xT may be built, executed and cleaned before 
the next test set in the scenario. This mode of use has the advantage that 
the entire \*(xT may be executed, without necessarily building all the 
test sets in advance. This mode of use has the disadvantage that you will
need to rebuild a test set before rerunning, which will take 
considerably longer than when it is built in advance.
.P
To do this, skip to the section entitled "Executing the \*(xT", 
and refer to the instructions in the sub-section entitled 
"Building, executing and cleaning tests using the \s-1TET\s0"
.H 2 "Building modified scenarios using the \s-1TET\s0"
.H 3 "Format of the scenario file"
The \s-1TET\s0 uses a scenario file to determine which test sets to build.
The file 
\fC$TET_ROOT/xtest/tet_scen\fP
is the default scenario file.
The format is basically a scenario name starting in column one,
followed by list of test sets to be built (each starting beyond column one).
Only one scenario named "all" is provided in the default scenario file.
.P
The names of the test sets are given relative to the directory 
$TET_ROOT/xtest, and must commence with a leading slash.
.H 3 "Modifying the scenario file"
The file 
\fC$TET_ROOT/xtest/tet_scen\fP
may be modified by removing lines corresponding to test sets which are not 
wanted. These will then simply not be built by the \s-1TCC\s0.
Alternatively, unwanted
lines may be commented out by placing \fC#\fP in column one of a line.
.P
It is recommended that the supplied scenario file should be saved if it is
modified.
.H 3 "Creating new scenario files"
A new scenario file may be created in the directory
\fC$TET_ROOT/xtest\fP.
The \s-1TCC\s0 will use this scenario file instead of the file 
\fC$TET_ROOT/xtest/tet_scen\fP
if it is passed via the \fC-s\fP option. For example
.cS
cd $TET_ROOT/xtest
tcc -b -s scenario_file [ -j journal_file ] [ -y string ] xtest all
.cE
.H 2 "Building tests without using the \s-1TET\s0"
See section 11, entitled
"Building, executing and reporting tests without using the \s-1TET\s0".
.H 2 "Building tests in space-saving format"
It is possible to build the tests in the \*(xT such that 
all the executable files in one section are links to a single 
executable file. This normally allows a considerable reduction 
in the disc space requirements for the \*(xT when fully built.
.P
Note that the names of the files built in space-saving format 
are different to the names of the separate executable files 
built using the instructions in previous sections. There is 
nothing to prevent both sets of executables being built (although
there is no value in this, and unnecessary disc space will be consumed).
.H 3 "Building tests in space-saving format using the \s-1TET\s0"
Before reading this section, read the section entitled "Building 
the tests using the \s-1TET\s0". This gives an explanation of the build mode 
of the \s-1TET\s0, and the structure of scenario files.
.P
A scenario named \fClinkbuild\fP is provided in a scenario file 
named \fClink_scen\fP in the directory 
$TET_ROOT/xtest. 
This enables the \s-1TCC\s0 to build the space-saving
executable files and create all the required links for each test set in
each section of the \*(xT. 
The -y option allows a particular space-saving 
executable for a single section to be built.
.P
Execute the command:
.cS
cd $TET_ROOT/xtest
tcc -b -s link_scen [ -j journal_file ] [ -y string ] xtest linkbuild
.cE
This command will execute the \s-1TET\s0 build tool in the \s-1TET\s0 configuration 
variable
.SM TET_BUILD_TOOL
(which is normally pmake),
in the top level directory of each section of the test suite.
.H 3 "Building tests in space-saving format without using the \s-1TET\s0"
This section describes how to build the space-saving
executable files for a particular section of the 
\*(xT directly without using the \s-1TET\s0.
.P
This can be simply done by calling pmake in the required directory.
For example, to build all the space-saving executable files for
section 5 of the \*(xT, execute the command:
.cS
cd $TET_ROOT/xtest/tset/CH05
pmake
.cE
.SK
.H 1 "Executing the \*(xT"
Once you have built the \*(xT as described in the previous sections,
work through the following sections to execute the tests.
.H 2 "Setting up your X server"
The first step is to ensure that the X server to be tested is correctly set up.
.H 3 "Formal verification testing"
A number of the tests within the \*(xT can only give reliable results 
if there is no window manager and no other clients making connections to
the X server. Thus, when conducting formal verification tests, there 
should be no window manager and no other clients connected to the X server.
.P
It is recommended that you close down and restart your X server before 
a formal verification test run, in order to ensure that results produced 
are repeatable and are not affected by earlier tests, although this is 
not strictly necessary.
.P
You should switch off the
screen saver if possible before starting formal verification tests.
This is because some X servers implement the screen saver in a way
which interferes with windows created by test suite clients, which may cause
misleading results. If the screen saver cannot be switched off, the 
time interval should be set so large as to prevent interference with the tests.
.P
You should also ensure that access control is disabled for the server 
under test, so that the test suite can make connections to the server.
Also (if the X server allows this) you should ensure that clients on the 
host system (as specified in the build 
configuration parameter 
.SM XTESTHOST ) 
can modify the access control list.
Some X servers support the -ac option which disables host-based access 
control mechanisms. If this option is supported, you should use it.
.H 3 "Informal testing and debugging"
Although no guarantee can be made that the tests within the \*(xT will give
correct results if there are window managers and other clients connected
to the X server, it is still possible to run many tests satisfactorily.
.P
This section gives some guidelines which may be helpful in running tests 
with a window manager present, and still deriving correct results.
The guidelines have been derived from the experience gained
during the development of the tests.
.P
Using these guidelines in connection with the instructions
in section 11,
entitled
"Building, executing and reporting tests without using the \s-1TET\s0",
gives a rapid means to investigate the results of particular tests in detail.
.P
.AL
.LI
Set XT_DEBUG_OVERRIDE_REDIRECT=Yes
in your execution configuration file. This is described in more detail in the 
next section.
.LI
Do not raise any windows on top of those created by
running tests.
.LI
Avoid having any windows at position (0,0). Note that some window managers
such as \fCtvtwm\fP
create their own "root" window at position (0,0).
This mainly affects tests for section 8 of the X11R4 Xlib specifications.
.LI
Be prepared to lose the input focus when tests are running
and don't forcibly restore it.
This mainly affects tests for section 8 of the X11R4 Xlib specifications.
.LE
.H 2 "Execute configuration parameters"
The next step is to set up the execution configuration file.
.P
All execution configuration parameters are contained in 
a configuration file that
forms part of the \s-1TET\s0.
This file should be edited to reflect the configuration of the X server 
to be tested and the underlying operating system on which Xlib
is implemented.
The file
.cS
\fC$TET_ROOT/xtest/tetexec.cfg\fP
.cE
contains all the parameters that are needed to execute the \*(xT.
The parameters are grouped in eight sections within the configuration file.
.P
Numeric execution parameters may be specified in decimal,
octal, or hexadecimal. Octal values must be a sequence of octal digits 
preceded by 0. Hexadecimal values must be a sequence of hexadecimal digits 
preceded by 0x or 0X.
.H 3 "Configuration parameters defined by the \s-1TET\s0"
.VL 5 0
.LI \s-1TET_EXEC_IN_PLACE\s0
.br
Setting this variable to 
.C False
indicates that files will be executed
in a temporary execution directory.
Use of a temporary execution directory for each test enables 
parallel execution of the test suite against multiple servers.
.P
Setting this variable to 
.C True
will give you improved performance if you are not attempting 
parallel execution of the test suite against multiple servers.
.cS
Eg: TET_EXEC_IN_PLACE=False
.cE
.LI \s-1TET_SAVE_FILES\s0
.br
This indicates which files generated during execution of
tests are to be saved for later examination. 
This line should not be altered.
.cS
Eg. TET_SAVE_FILES=Err*.err,*.sav
.cE
.LE
.H 3 "Configuration Parameters for the \*(xT"
The following parameters are used in many places in the \*(xT. 
These should be set to match the 
X server to be tested and the underlying operating system on which Xlib 
is implemented.
.VL 5 0
.LI \s-1XT_DISPLAY\s0
.br
This should be set to a display string that can be passed to XOpenDisplay,
to access the display under test.
It must include a screen;
all testing is done for a particular screen.
.cS
Eg: XT_DISPLAY=:0.0
.cE
.LI \s-1XT_ALT_SCREEN\s0
.br
If the display supports more than one screen,
this parameter should be set to the number of a screen 
that is different from that incorporated in the XT_DISPLAY variable.
.br
Set to the string 
.SM UNSUPPORTED 
if only one screen is available.
.br
Note that this should be a screen number, not a display string that can
be passed to XOpenDisplay.
.cS
Eg: XT_ALT_SCREEN=1
.cE
.LI \s-1XT_FONTPATH\s0
.br
This should be set to a comma separated list that 
is a valid font path for the X server. It should include at least 
the components of the default font path for the X server, enabling the cursor 
font to be accessed.
One of the components must be the directory 
in which the test fonts were installed (see the section entitled "Compiling
and installing the test fonts").
.P
This parameter will be used to set the font path for specific test purposes
which access the test fonts. The font path is restored on completion
of the specific test purposes.
.cS
Eg: \s-1XT_FONTPATH=/usr/lib/X11/fonts/xtest/,/usr/lib/X11/fonts/misc/\s0
.cE
.LI \s-1XT_SPEEDFACTOR\s0
.br
This is a speedfactor which should be set to reflect the relative delay 
in response of the underlying operating system and X server combined.
Co-operating processes which 
must synchronize allow a time delay in proportion to this speedfactor, to 
account for scheduling delays in the underlying operating system and X server.
This should be set to a number greater than or equal to one.
There should be no need to change the default unless the round trip time to
the X server can be very long ( >15 seconds);
in this case set this parameter to a
value larger than the maximum round trip time divided by 3.
.cS
Eg: XT_SPEEDFACTOR=5
.cE
.LI \s-1XT_RESET_DELAY\s0
.br
Specifies a delay time in seconds.
Set this to be a time which is greater than or equal to the maximum time
required by your server to reset when the last client is closed.
The test suite pauses for this time whenever a connection is about to be 
opened and the server may be resetting.
The server may be resetting when the test case is entered (in startup())
as a result of closing the last connection in the previous test case.
The server also resets in a few places in the test for XCloseDisplay().
.cS
Eg. XT_RESET_DELAY=1
.cE
.LI \s-1XT_EXTENSIONS\s0
.br
Specifies whether you wish to test the extended assertions
which require the XTEST extension.
Set this to Yes if the XTEST extension is available on your system,
and you have configured the test suite to use the XTEST extension,
and you want to execute these tests, otherwise set to No.
.br
.cS
Eg. XT_EXTENSIONS=No
.cE
.LE
.H 3 "Configuration parameters for specific tests"
The following parameters are used to control 
one or more specific test purposes in the \*(xT. 
These should be set to appropriate values for the X server to be tested.
.P
These parameters may cause temporary changes in the settings 
of the X server under test (such as the font path).
Settings are restored on completion of the specific test purposes.
.VL 5 0
.LI \s-1XT_VISUAL_CLASSES\s0
.br
A space separated list of the visual classes that
are supported for the screen given by XT_DISPLAY.  Each visual class
is followed by a list of depths at which the class is supported
(enclosed by brackets and separated by commas with no spaces).
Visual classes and depths that are supported only by other screens should
not be included.
.br
Note that this parameter is only used to check the correctness of the values
returned by XMatchVisualInfo and XGetVisualInfo. Other tests which loop
over visuals obtain the values by calling these functions.
.cS
Eg. XT_VISUAL_CLASSES=StaticGray(8) GrayScale(8) StaticColor(8) 
                      PseudoColor(8) TrueColor(8) DirectColor(8)
\fR(This must be typed as one line.)\fP
.cE
.LI \s-1XT_FONTCURSOR_GOOD\s0
.br
This specifies the number of a glyph in the 
default cursor font known to exist. 
.SM XT_FONTCURSOR_GOOD+2
should also be a glyph in the
default cursor font.
Neither of these should be the same as the X server's default cursor.
.cS
Eg: XT_FONTCURSOR_GOOD=2
.cE
.LI \s-1XT_FONTCURSOR_BAD\s0
.br
This specifies the number of a glyph in the 
default cursor font known not to exist. 
If no such value exists, set to
.SM UNSUPPORTED .
.cS
Eg: XT_FONTCURSOR_BAD=9999
.cE
.LI \s-1XT_FONTPATH_GOOD\s0
.br
This should be set to a comma separated list that
is a valid font path for the X server.
It should
be different from XT_FONTPATH. It need not contain the 
test fonts.
.cS
Eg: \s-1XT_FONTPATH_GOOD=/usr/lib/X11/fonts/100dpi/,/usr/lib/X11/fonts/75dpi/\s0
.cE
.LI \s-1XT_FONTPATH_BAD\s0
.br
This should be set to a comma separated list that 
is an invalid font path for the X server.
If you cannot determine a suitable value, set to 
.SM UNSUPPORTED .
There is no default value - by default, tests which use this parameter
will be reported as 
.SM UNSUPPORTED .
.cS
Eg: XT_FONTPATH_BAD=/jfkdsjfksl
.cE
.LI \s-1XT_BAD_FONT_NAME\s0
.br
This should be set to a non-existent font name.
.cS
XT_BAD_FONT_NAME=non-existent-font-name
.cE
.LI \s-1XT_GOOD_COLORNAME\s0
.br
This should be set to the name of a colour 
which exists in the colour database for the X server.
.cS
Eg: XT_GOOD_COLORNAME=red
.cE
.LI \s-1XT_BAD_COLORNAME\s0
.br
This should be set to the name of a colour 
which does not exist in the colour database for the X server.
.cS
Eg: XT_BAD_COLORNAME=nosuchcolour
.cE
.LI \s-1XT_DISPLAYMOTIONBUFFERSIZE\s0
.br
This should be set to a non-zero value (the value
returned by XDisplayMotionBufferSize) if the X server supports a more complete 
history of pointer motion than that provided by event notification, or
zero otherwise. The
more complete history is made available via the Xlib functions 
XDisplayMotionBufferSize and XGetMotionEvents.
.cS
Eg: XT_DISPLAYMOTIONBUFFERSIZE=256
.cE
.LE
.H 3 "Configuration parameters for Display functions"
The following parameters are used to control one or more test purposes for Xlib 
Display functions which are in section 2 of the X11R4 Xlib specifications.
These should be set to match the display specified in the XT_DISPLAY parameter. 
.P
Some of these parameters are specific to the particular screen of 
the display under test. This is also specified in the XT_DISPLAY parameter.
.P
Settings to these parameters will not cause any change in the settings 
of the X server under test.
.P
Suitable values for most of these parameters can be obtained from the 
output of the X11 utility 
.C xdpyinfo .
.VL 5 0
.LI \s-1XT_SCREEN_COUNT\s0
.br
This parameter should be set to the number of screens
available on the display as returned by XScreenCount.
.br
.cS
Eg: XT_SCREEN_COUNT=2
.cE
.LI \s-1XT_PIXMAP_DEPTHS\s0
.br
A space separated list of depths supported by the specified 
screen of the display that can be used for pixmaps.
.cS
Eg: XT_PIXMAP_DEPTHS=1 8
.cE
.LI \s-1XT_BLACK_PIXEL\s0
.br
This parameter should be set to the black pixel value 
of the specified screen of the display.
.cS
Eg: XT_BLACK_PIXEL=1
.cE
.LI \s-1XT_WHITE_PIXEL\s0
.br
This parameter should be set to the white pixel value 
of the specified screen of the display.
.cS
Eg: XT_WHITE_PIXEL=0
.cE
.LI \s-1XT_HEIGHT_MM\s0
.br
This parameter should be set to the height in millimeters
of the specified screen of the display.
.cS
Eg: XT_HEIGHT_MM=254
.cE
.LI \s-1XT_WIDTH_MM\s0
.br
This parameter should be set to the width in millimeters
of the specified screen of the display.
.cS
Eg: XT_WIDTH_MM=325
.cE
.LI \s-1XT_PROTOCOL_VERSION\s0
.br
This should be set to the major version number (11) 
of the X protocol as returned by XProtocolVersion.
.cS
Eg. XT_PROTOCOL_VERSION=11
.cE
.LI \s-1XT_PROTOCOL_REVISION\s0
.br
This should be set to the minor protocol 
revision number as returned by XProtocolRevision.
.cS
Eg. XT_PROTOCOL_REVISION=0
.cE
.LI \s-1XT_SERVER_VENDOR\s0
.br
This should be set to the X server vendor string
as returned by XServerVendor.
.cS
Eg: XT_SERVER_VENDOR=MIT X Consortium
.cE
.LI \s-1XT_VENDOR_RELEASE\s0
.br
This should be set to the X server vendor's release 
number as returned by XVendorRelease.
.cS
Eg. XT_VENDOR_RELEASE=5000
.cE
.LI \s-1XT_DOES_SAVE_UNDERS\s0
.br
Set this to Yes if the specified screen of the display
supports save unders (indicated by XDoesSaveUnders returning True)
otherwise set to No.
.cS
Eg. XT_DOES_SAVE_UNDERS=Yes
.cE
.LI \s-1XT_DOES_BACKING_STORE\s0
.br
Set this to the following value:
.br
0 - the specified screen supports backing store NotUseful
.br
1 - the specified screen supports backing store WhenMapped
.br
2 - the specified screen supports backing store Always
.br
The way the specified screen supports backing store is indicated by the
return value of XDoesBackingStore.
.cS
Eg. XT_DOES_BACKING_STORE=2
.cE
.LE
.H 3 "Configuration parameters for connection tests"
The following parameters are used to control 
one or more test purposes for XOpenDisplay, XCloseDisplay and 
XConnectionNumber.
These should be set to match the display specified in the XT_DISPLAY parameter
and the characteristics of the underlying operating system.
.P
Settings to these parameters will not cause any change in the settings 
of the X server under test.
.P
These parameters are not used when making connections to the 
X server in other tests.
.VL 5 0
.LI \s-1XT_POSIX_SYSTEM\s0
.br
This may be set to Yes to indicate that the 
underlying operating system is a POSIX system. If this parameter is
set to Yes, some extended assertions which describe implementation 
dependent functionality will be tested assuming POSIX concepts.
.cS
Eg. XT_POSIX_SYSTEM=Yes
.cE
.LI \s-1XT_DECNET\s0
.br
Set this to Yes if clients can connect to the X server under 
test using DECnet.
This will be used (on a POSIX system)
in the tests for XOpenDisplay.
.cS
Eg. XT_DECNET=No
.cE
.LI \s-1XT_TCP\s0
.br
Set this to Yes if clients can connect to the X server under 
test using TCP streams.
This will be used (on a POSIX system)
in the tests for XOpenDisplay.
.cS
Eg. XT_TCP=Yes
.cE
.LI \s-1XT_DISPLAYHOST\s0
.br
Set this to the hostname of the machine on which the display
is physically attached. This will be used instead of XT_DISPLAY
(on a POSIX system) 
in the tests for XOpenDisplay which specifically test the hostname 
component of the display name.
.P
Note that this may not be the same as the machine on which the 
test suite clients execute (XTESTHOST).
.cS
Eg. XT_DISPLAYHOST=xdisplay.lcs.mit.edu
.cE
.LI \s-1XT_LOCAL\s0
.br
Set this to Yes if clients can connect to a local X server 
without passing a hostname to XOpenDisplay.
This will be used (on a POSIX system)
in the tests for XOpenDisplay.
This is usually the case when the X server under test is running on the
same platform as the \*(xT.
When a hostname is omitted, the Xlib implementation of XOpenDisplay 
can use the fastest available transport mechanism to make local connections.
.cS
Eg. XT_LOCAL=No
.cE
.LE
.P
.H 3 "Configuration Parameters which do not affect test results"
There are a number of execution configuration parameters which can be used
to reduce the size of the journal file, or dump out more information from the 
test suite.
They will not alter the behaviour of the tests or the test results.
.P
.VL 5 0
.LI \s-1XT_SAVE_SERVER_IMAGE\s0
.br
When set to Yes,
the image produced by the server 
that is compared with the known good image is dumped to a file 
with suffix ".sav" .
.cS
Eg: XT_SAVE_SERVER_IMAGE=Yes
.cE
.LI \s-1XT_OPTION_NO_CHECK\s0
.br
This may be set to Yes to suppress the journal file
records containing 
.SM CHECK 
keywords. Refer to appendix D for 
information on the contents of these messages.
.cS
Eg: XT_OPTION_NO_CHECK=Yes
.cE
.LI \s-1XT_OPTION_NO_TRACE\s0
.br
This may be set to Yes to suppress the journal file
records containing 
.SM TRACE 
keywords. Refer to appendix D for 
information on the contents of these messages.
.cS
Eg: XT_OPTION_NO_TRACE=Yes
.cE
.LE
.P
.H 3 "Configuration Parameters for debugging tests"
There are a number of execution configuration parameters which should
not be set when performing verification test runs. These are intended
for debugging purposes. These parameters may affect the behaviour of some test 
purposes if they are set to assist debugging.
.P
.VL 5 0
.LI \s-1XT_DEBUG\s0
.br
This may be set to a debugging level.
A higher level produces more debugging output. Output is only 
produced by the test suite at levels 1, 2 and 3. Setting
this variable to 0 produces no debug output, and 3 gives everything
possible (setting this variable to 3 can give an enormous volume of output
so you should not do this when running large numbers of test sets).
.cS
Eg: XT_DEBUG=0
.cE
.LI \s-1XT_DEBUG_OVERRIDE_REDIRECT\s0
.br
When set to 
.C Yes , 
windows are created with
override_redirect set. 
This enables tests to be run more easily with a
window manager running on the same screen.
This should not be set to 
.C Yes 
for verification tests.  
.cS
Eg: XT_DEBUG_OVERRIDE_REDIRECT=No
.cE
.LI \s-1XT_DEBUG_PAUSE_AFTER\s0
.br
When set to 
.C Yes , 
the test pauses after each call to the Xlib
function being tested, until Carriage Return is entered.
This is useful to enable the results of
graphics operations to be observed.
This should not be set to 
.C Yes 
for verification tests.
.cS
Eg: XT_DEBUG_PAUSE_AFTER=No
.cE
.LI \s-1XT_DEBUG_PIXMAP_ONLY\s0
.br
When set to 
.C Yes , 
tests which would normally loop over
both windows and pixmaps are restricted to loop over just pixmaps.
This is useful for speeding up the 
execution of the test set.
This should not be set to 
.C Yes 
for verification tests.
.P
If 
.SM XT_DEBUG_WINDOW_ONLY 
is also set to 
.C Yes ,
some tests will report 
.SM UNRESOLVED 
due to the fact that nothing has been tested.
.cS
Eg: XT_DEBUG_PIXMAP_ONLY=No
.cE
.LI \s-1XT_DEBUG_WINDOW_ONLY\s0
.br
When set to 
.C Yes , 
tests which would normally loop over
both windows and pixmaps are restricted to loop over just windows.
This is useful for speeding up the 
execution of the test set.
This should not be set to 
.C Yes 
for verification tests.
.P
If 
.SM XT_DEBUG_PIXMAP_ONLY 
is also set to 
.C Yes ,
some tests will report 
.SM UNRESOLVED 
due to the fact that nothing has been tested.
.cS
Eg: XT_DEBUG_WINDOW_ONLY=No
.cE
.LI \s-1XT_DEBUG_DEFAULT_DEPTHS\s0
.br
When set to 
.C Yes , 
tests which would normally loop over multiple
depths are restricted to test just the first visual returned by
XGetVisualInfo and/or the first pixmap depth returned by XListDepths
(depending on whether 
.SM XT_DEBUG_PIXMAP_ONLY
or 
.SM XT_DEBUG_WINDOW_ONLY
is also set).
This is useful for speeding up the 
execution of the test set.
This should not be set to 
.C Yes 
for verification tests.
.P
Note that the first visual returned by XGetVisualInfo may not be the default 
visual for the screen.
.cS
Eg: XT_DEBUG_DEFAULT_DEPTHS=No
.cE
.LI \s-1XT_DEBUG_VISUAL_IDS\s0
.br
When set to a non-empty string, tests which would 
normally loop over multiple depths are restricted to test just the 
visuals ID's listed. Note that visual ID's for visuals on more than 
one screen may be entered, but those used will depend on whether the test 
being executed uses visuals on the default screen or alternate screen.
The visuals ID's should be entered in decimal, octal or hexadecimal
and separated with commas and with no intervening spaces.
This should not be set to a non-empty string for verification tests.
.cS
Eg. XT_DEBUG_VISUAL_IDS=0x22,0x24,0x27
.cE
.LI \s-1XT_DEBUG_NO_PIXCHECK\s0
.br
When set to 
.C Yes , 
tests
which would normally perform pixmap verification omit this (all other
processing is performed in those tests as normal).
Pixmap verification is a scheme which compares the image produced by the 
X server with a known good image file which is part of the \*(xT (this is 
described further in the section entitled "Examining Image Files").
This should not be set to 
.C Yes 
for verification tests.
.cS
Eg: XT_DEBUG_NO_PIXCHECK=No
.cE
.LI \s-1XT_DEBUG_BYTE_SEX\s0
.br
When set to 
.SM NATIVE ,
.SM REVERSE ,
.SM MSB 
or 
.SM LSB , 
the X Protocol tests will only be executed with the specified byte sex. 
When set to
.SM BOTH ,
the X Protocol tests make connections to the X server using
both the native and reversed byte sex.
.P
Note: The parameter should always be set to 
.SM NATIVE
when the build configuration parameter
.SM XP_OPEN_DIS
was set to XlibOpaque.c
.cS
Eg: XT_DEBUG_BYTE_SEX=NATIVE
.cE
.LI \s-1XT_DEBUG_VISUAL_CHECK\s0
.br
When set to a non-zero value, the X Protocol tests
will pause for the specified time interval (in seconds), to enable a visual
check to be performed on the displayed screen contents.
.cS
Eg: XT_DEBUG_VISUAL_CHECK=5
.cE
.H 3 "Configuration Parameters used only during test development"
This section defines a number of parameters that are used only when
generating known good image files. These are not intended to be modified 
and need not be used when running the test suite.
They are only used in the development environment
at UniSoft when generating known good image files.
.P
.VL 5 0
.LI \s-1XT_FONTDIR\s0
.br
The directory in which the xtest fonts are located 
(before being installed).
This must be set such that appending a string gives a valid file name.
This is normally set to \fC$TET_ROOT/xtest/fonts/\fP.
.cS
Eg: XT_FONTDIR=/usr/mit/testsuite/xtest/fonts/
.cE
.LE
.H 2 "Executing tests using the \s-1TET\s0"
The \*(xT is executed by invoking the execute mode of the Test Case
Controller.
.cS
cd $TET_ROOT/xtest
tcc -e [ -s scenario_file ] [ -j journal_file ] [ -x config_file ] 
                                                [ -y string ] xtest all
.cE
.VL 5 0
.LI \fC-e\fP
.br
This invokes the \s-1TCC\s0 in execute mode.
.LI "\fC-s scenario_file\fP"
.br
This option executes the test sets in the named scenario file.
The default is a file named \fCtet_scen\fP in the directory 
\fC$TET_ROOT/xtest\fP.
For more details refer to the section entitled 
"Executing modified scenarios using the \s-1TET\s0".
.LI "\fC-j journal_file\fP"
.br
This option sends the test results to the named journal file.
The default is a file named \fCjournal\fP in a newly created sub-directory 
of \fC$TET_ROOT/xtest/results\fP. Sub-directories are created with sequential
four digit numbers, with the 
.SM TCC
flags (in this case "e") appended.
The \s-1TCC\s0 will exit if the specified journal file already exists, thus the
journal file should be renamed or removed
before attempting to execute the \s-1TCC\s0.
.LI "\fC-x config_file\fP"
.br
This is an option to run the test suite using the information in a 
modified execution configuration file named 
.C config_file .
The default is 
.C tetexec.cfg .
.LI "\fC-y string\fP"
.br
This option only executes tests which include the specified string in the 
scenario file line. This may be used to execute specific sections or individual
test sets.
.LI \fCxtest\fP
.br
This is the name of the test suite.
It determines the directory under $\s-1TET_ROOT\s0
where the test suite is to be found.
.LI \fCall\fP
.br
This is the scenario name in the default scenario file
\fC$TET_ROOT/xtest/tet_scen\fP.
For more details refer to the section entitled 
"Executing modified scenarios using the \s-1TET\s0".
.LE
.P
A journal file 
will be produced.
More information on the contents of the journal file is given in 
appendix C.
.P
Note: If the \s-1TCC\s0
terminates due to receipt of a signal which 
cannot be caught, the \s-1TCC\s0
may leave lock files in the test source directories. Subsequent 
attempts to restart the \s-1TCC\s0 may give error messages 
saying that a lock file was encountered. At this point 
\s-1TCC\s0
may suspend the build. It may be 
necessary to find and remove files or directories named \fCtet_lock\fP 
before continuing.
.H 2 "Building, executing and cleaning tests using the \s-1TET\s0"
Each test in the \*(xT may be built, executed and cleaned before 
the next test set in the scenario. This mode of use has the advantage that 
the entire \*(xT may be executed without necessarily building all the 
test sets in advance, thus ensuring disc space is conserved throughout.
This mode of use has the disadvantage that you will
need to rebuild a test set before rerunning, which will take 
considerably longer than if it is built in advance.
.P
The \*(xT is built, executed and cleaned 
by simultaneously invoking the build, execute and clean modes of the Test Case
Controller.
.cS
cd $TET_ROOT/xtest
tcc -bec [ -s scenario_file ] [ -j journal_file ] [ -x config_file ]
                                                  [ -y string ] xtest all
.cE
.VL 5 0
.LI \fC-b\fP
This invokes the \s-1TCC\s0 in build mode.
.LI \fC-e\fP
This invokes the \s-1TCC\s0 in execute mode.
.LI \fC-c\fP
This invokes the \s-1TCC\s0 in clean mode.
.LE
.P
The other options are as described in the earlier section entitled
"Executing tests using the \s-1TET\s0".
.P
A journal file 
will be produced. This contains for each test set in order the results of 
the build, followed by the test results, followed by the results of the clean.
More information on the contents of the journal file is given in 
appendix C.
.P
The default journal file is named \fCjournal\fP in a newly created sub-directory 
of \fC$TET_ROOT/xtest/results\fP. Sub-directories are created with sequential
four digit numbers, with the 
.SM TCC
flags (in this case "bec") appended.
.H 2 "Executing modified scenarios using the \s-1TET\s0"
.H 3 "Format of the scenario file"
The \s-1TET\s0 uses a scenario file to determine which test sets to execute.
The file 
\fC$TET_ROOT/xtest/tet_scen\fP
is the default scenario file.
The format is basically a scenario name starting in column one,
followed by list of test sets to be executed (each starting beyond column one).
Only one scenario named "all" is provided in the default scenario file.
.P
The names of the test sets are given relative to the directory 
$TET_ROOT/xtest, and must commence with a leading slash.
.H 3 "Modifying the scenario file"
The file 
\fC$TET_ROOT/xtest/tet_scen\fP
may be modified by removing lines corresponding to test sets which are not 
wanted. These will then simply not be executed by the \s-1TCC\s0.
Alternatively, unwanted
lines may be commented out by placing \fC#\fP at the start of the line.
.P
If you wish to execute just a subset of the test purposes in a test set, 
refer to the section below entitled "Executing individual test purposes
using the \s-1TET\s0".
.P
It is recommended that the supplied scenario file should be saved if it is
modified.
.H 3 "Creating new scenario files"
A new scenario file may be created in the directory
\fC$TET_ROOT/xtest\fP.
The \s-1TCC\s0 will use this scenario file instead of the file 
\fC$TET_ROOT/xtest/tet_scen\fP
if it is passed via the \fC-s\fP option. For example
.cS
cd $TET_ROOT/xtest
tcc -e -s scenario_file [ -j journal_file ] [ -x config_file ]
                                            [ -y string ] xtest all
.cE
.H 2 "Executing individual test purposes using the \s-1TET\s0"
Each assertion in the \*(xT has separate test code which is known as a
test purpose.
We have arranged that each test purpose is also
a separately invocable component,
and that the invocable component number is identical 
to the test purpose number.
.P
The expression within the braces 
at the end of a line within a scenario file is an 
invocable component list (or IC_list). 
The default invocable component list \fCall\fP causes the 
\s-1TCC\s0 to execute all invocable components in a test set.
.P
By altering the invocable component list for a test set,
particular invocable components of interest can be 
executed.
.P
The invocable component list consists of one or more elements separated 
by commas. Each element is either an invocable component number,
or a range of invocable component numbers separated by a dash.
.P
This is useful for quickly executing a particular test purpose of interest
for example:
.cS
/tset/CH05/stclpmsk/Test{3}
.cE
This is also useful for executing all test purposes except one known 
to cause a system error. This may be useful if a particular test purpose
causes your X server to exit (at present the \s-1TET\s0 provides no high level
control facilities to conditionally cancel later test sets).
For example:
.cS
/tset/CH05/stclpmsk/Test{1-2,4-6}
.cE
.P
Note that the placement of windows used by the test suite may differ
when an earlier test purpose is not executed. It is intended that test 
purposes produce the same results regardless of window placement.
.H 2 "Executing tests without using the \s-1TET\s0"
See section 11, entitled
"Building, executing and reporting tests without using the \s-1TET\s0".
.H 2 "Executing tests in space-saving format using the \s-1TET\s0"
Before reading this section, read the section entitled "Building 
tests in space-saving format".
When you have built all the sections of the test suite in space-saving 
format, you can execute all the tests in the test suite using
the instructions in this section.
.P
A scenario named \fClinkexec\fP is provided in a scenario file 
named \fClink_scen\fP in the directory 
$TET_ROOT/xtest. 
This enables the \s-1TCC\s0 to execute the space-saving
executable files which have been built.
.P
Execute the command:
.cS
cd $TET_ROOT/xtest
tcc -e -s link_scen [ -j journal_file ] [ -x config_file ]
                                        [ -y string ] xtest linkexec
.cE
.SK
.H 1 "Report writer"
A basic report writer 
\fCrpt\fP
is included with the \*(xT.
It extracts and formats the main information from a 
TET journal file produced by executing the \s-1TCC\s0 in execute 
mode, or build-execute-clean mode.
It does not format the \s-1TET\s0 journal file produced by the 
\s-1TCC\s0 in build only or clean only mode. 
The main features of the \s-1TET\s0 journal file produced by the \s-1TCC\s0 in
execute or build-execute-clean mode are described in appendix\ C.
.P
Execute the report writer as follows:
.P
.cS
rpt [ -t ] [ -d ] [ -p ] [ -s ] [ -f file ]
.cE
With only the -f argument, \fCrpt\fP lists the results of each test purpose
for all test sets that appear in the journal file \fCfile\fP. 
The default is the file named
.C journal
in the highest numbered subdirectory of the
.C $TET_ROOT/xtest/results
directory that has an 'e' suffix.
.P
The reason for any test result code which is other than PASS is printed out.
This is done by copying the test information messages of type REPORT. 
For further details, see appendix D.
.P
A warning message is printed if a test information message of type REPORT
is given in a test purpose which produced a test result code PASS.
.P
The results for each test set are followed
by a summary of the number of test purposes in the test set
which produced each result code type.
.P
There is no overall summary list of results for all test sets in the journal 
file.
.P
.VL 5 0
.LI -t
.br
Test information messages of type TRACE in the test purposes
specified are printed.
For further details, see appendix D.
.LI -d
.br
Test information messages of type TRACE or DEBUG in the test purposes
specified are printed.
For further details, see appendix D.
.LI -p
.br
Output is restricted to omit reporting on test purposes that
resolve to \s-1PASS\s0, \s-1UNSUPPORTED\s0, \s-1UNTESTED\s0
or \s-1NOTINUSE\s0 \*(EM thereby
reporting only tests showing possible errors.
.LI -s
.br
The result summaries after the end of each test set are omitted.
.LE
.SK
.H 1 "Examining image files"
.H 2 "Generating pixmap error files"
During the test run, discrepancies may be encountered between the image
displayed by the server and the known good image. The known good image 
may have been obtained from a known good image file supplied with the 
release, or it may have been determined analytically. 
.P
Should a discrepancy be encountered, the test purpose 
will give a result code of FAIL. The failure reason message will 
name a pixmap error file in which is contained both the known good image and 
the server image. 
.P
A debug option has been provided, which skips any verification of the 
image produced by the server with known good image files. This 
is done by setting the execution configuration parameter 
.SM XT_DEBUG_NO_PIXCHECK 
to \fCYes\fP.
.H 2 "Pixmap error file naming scheme"
Each invocation of the 
.SM TCC
creates a sub-directory 
in \fC$TET_ROOT/xtest/results\fP. Sub-directories are created with sequential
four digit numbers, with the 
.SM TCC
flags ("e" or "bec") appended. The default
.SM TET
journal is a file named
\fCjournal\fP created in this directory.
.P
Pixmap error files are stored in a directory tree created within the 
newly created results sub-directory. So, for example, when the 
line 
.cS
/tset/CH06/drwln
.cE
is executed in a scenario file, pixmap error files might be produced
in a directory named
\fC$TET_ROOT/xtest/results/0001bec/tset/CH06/drwln\fP.
.P
The creation of a new results directory tree for each execution of the 
.SM TCC
enables results to be obtained in parallel against multiple 
X servers.
.P
Pixmap error files are named Err\fCnnnn\fP.err, 
where \fCnnnn\fP
is a four digit number. This number does not
correspond to the number of the test purpose which caused the error.
.P 
Note - when tests are executed without using the 
.SM TCC
the error files are produced in the current directory.
.H 2 "Known good image file naming scheme"
All the required known good image files for the test programs in the 
\*(xT (as supplied) have been created in advance.
The known good image files for each test program 
are supplied in the \*(xT in the test set directory in which the dot-m 
file is supplied. They are named a\fCnnn\fP.dat, where \fCnnn\fP is the 
number of the test purpose for which the known good image file was generated.
.P
More details of the contents of this release are in appendix A.
.H 2 "Using blowup to view image files"
The contents of the two images in a pixmap error file
may be compared by using the blowup utility.
.P
Also, a known good image file may be viewed directly. 
.P
The file formats of the error file and the known good image file are 
the same. The blowup utility detects which file type is being viewed 
by means of file name. For this reason, do not rename the 
pixmap error or known good image files.
.H 3 "Blowup command"
The blowup utility may be used to view one or more pixmap error files or 
known good image files as follows:
.P
.cS
blowup [-z zoom_factor] [-f font] [-d display] [-colour] file(s)
.cE
.VL 5 0
.LI "\fC-z zoom_factor\fP"
.br
This option sets the magnification factor in all the blowup windows.
.LI "\fC-f font\fP"
.br
This option ensures that 
.C font
is used rather than the default font. The default font is 6x10.
.LI "\fC-d display\fP"
.br
This option uses the display named 
.C display
for the display windows.
.LI "\fC-colour\fP"
.br
On a colour display, this option will display different pixel
values in different colours corresponding to that server's colour table. 
No attempt is made to preserve colours between different servers.
.LE
.H 3 "Blowup windows"
Two windows are created. The first is called Comparison, 
and the second is called Blowup.
The Blowup window 
shows a magnified version of a portion of the Comparison window, 
which is indicated in the Comparison window by a rectangle. A user 
interface menu is shown in the Blowup window.
.P
The title of the Comparison window will change to 
"Server Data", then to "Pixval Data" and then back to "Comparison" 
when the "B/G/Both" option on the menu is used.
.H 3 "Selection of a viewing region"
This may be done in one of three ways:
.AL
.LI
Click in the Comparison window.
.LI
Click in a square in the Blowup window. This becomes the new centre square
in that window.
.LI
Choose the "next error" option on the menu. The next pixel at which there
is a discrepancy will become the new centre square in the Blowup 
window.
.LE
.H 3 "Information displayed"
The value stored in the centre pixel
and its coordinates are shown as the top items 
in the menu. Under some circumstances, the expected pixel value will
be shown to the right of the actual value.
.H 3 "Display of errors"
When the "B/G/Both" option is set to Both, and the title of the Comparison 
window is Comparison,
errors are displayed in two ways: one for each window.
.VL 5 0
.LI
In the Comparison window pixels set to non-zero in the "good image"
but set incorrectly in the "server data" are shown as a cross (X).
.LI
In the blowup window these are shown as a white square with
a cross (X) through it.
.LI
In the Comparison window pixels set to zero in the "good image"
but set incorrectly in the "server data" are shown as shaded squares.
.LI
In the blowup window these are shown as a black square with
a white cross through it.
.LE
.P
The reason that we have proposed the two different methods of displaying errors
is as follows. One normally has a higher magnification in the Blowup
window and the use of a cross (X) through incorrect pixels
is good, and simple to remember
at this level of zoom. In the Comparison window 
this style of display
does not work well at the lower magnification levels; all the crosses merge to
a blur so it is hard to see what type of error is being displayed.
.H 3 "Commands (via menu in the Blowup window)"
All of the commands are invoked by clicking the left mouse button when the
corresponding menu item is highlighted (inverted). The available commands are,
from top to bottom:
.VL 5 0
.LI B/G/Both	
.br
Show Bad (Server Data), Good (Pixval Data) or Both
(Comparison). Clicking in this advances around the
cycle
.ft C
.DS
Bad ----> Good -> Both
 \------<------<----/
.DE
.ft
The Comparison window's name changes to reflect the
current state.
.P
If a known good image file is being displayed then only the Good
option is available. A pixmap error file is required for this
command to be useful.
.LI color/mono	
.br
Use colour/monochrome in the Blowup window.
.LI "next error"	
.br
Advance centre pixel point to be next pixel at which there is a 
discrepancy.
.LI "sub-zoom +"
.br
Zoom in (make bigger by zoomfactor) on the Blowup window
.LI "sub-zoom -"
.br
Zoom out (make smaller by zoomfactor) on the Blowup window
.LI "quit"
.br
Quit from the blowup utility.
.LI "big-zoom +"
.br
Zoom in (make bigger by zoomfactor) on the Comparison window
.LI "big-zoom -"
.br
Zoom out (make smaller by zoomfactor) on the Comparison window
.LI "next"
.br
View next file in the list. The Blowup window will
be removed and a new one created for each file. The
size, and zoom factor, of the Comparison window will
be preserved across files.
.LE
.SK
.H 1 "Cleaning the tests"
.H 2 "Cleaning tests using the \s-1TET\s0"
The entire \*(xT can be cleaned by using the 
clean mode of the \s-1TCC\s0. In this mode, the clean configuration
parameters in the file 
.C $TET_ROOT/xtest/tetclean.cfg 
are used to clean each test 
set in the \*(xT separately. Previously built test set executables 
and object files are removed.
.P
.cS
cd $TET_ROOT/xtest
tcc -c [ -s scenario_file ] [ -j journal_file ] [ -y string ] xtest all
.cE
.VL 5 0
.LI \fC-c\fP
.br
This invokes the \s-1TCC\s0 in clean mode.
.LI "\fC-s scenario_file\fP"
.br
This option cleans the test sets in the named scenario file.
The default is a file named \fCtet_scen\fP in the directory 
\fC$TET_ROOT/xtest\fP.
For more details refer to the section entitled 
"Cleaning modified scenarios using the \s-1TET\s0".
.LI "\fC-j journal_file\fP"
.br
This option sends the output of the clean to the named journal file.
The default is a file named \fCjournal\fP in a newly created sub-directory 
of \fC$TET_ROOT/xtest/results\fP. Sub-directories are created with sequential
four digit numbers, with the 
.SM TCC
flags (in this case "c") appended.
The \s-1TCC\s0 will exit if the specified journal file already exists, thus the
journal file should be renamed or removed
before attempting to execute the \s-1TCC\s0.
.LI "\fC-y string\fP"
.br
This option only cleans tests which include the specified string in the 
scenario file line. This may be used to clean specific sections or individual
test sets.
.LI \fCxtest\fP
.br
This is the name of the test suite.
It determines the directory under $\s-1TET_ROOT\s0
where the test suite is to be found.
.LI \fCall\fP
.br
This is the scenario name in the default scenario file
\fC$TET_ROOT/xtest/tet_scen\fP.
For more details refer to the section entitled 
"Cleaning modified scenarios using the \s-1TET\s0".
.LE
.P
This will execute the \s-1TET\s0 clean tool in the \s-1TET\s0 configuration 
variable
.SM TET_CLEAN_TOOL
(which is normally pclean),
in each test set directory of the \*(xT.
.P
The journal file should be examined to verify
that the clean process succeeded.
The report writer \fCrpt\fP cannot interpret the contents 
of a journal file produced during the clean process.
.P
Note: If the \s-1TCC\s0
terminates due to receipt of a signal which 
cannot be caught, the \s-1TCC\s0
may leave lock files in the test source directories. Subsequent 
attempts to restart the \s-1TCC\s0 may give error messages 
saying that a lock file was encountered. At this point 
\s-1TCC\s0
may suspend the build. It may be 
necessary to find and remove files or directories named \fCtet_lock\fP 
before continuing.
.H 2 "Cleaning modified scenarios using the \s-1TET\s0"
.H 3 "Format of the scenario file"
Refer to the earlier section "Building modified scenarios using the \s-1TET\s0".
.H 3 "Modifying the scenario file"
Refer to the earlier section "Building modified scenarios using the \s-1TET\s0".
.H 3 "Creating new scenario files"
A new scenario file may be created in the directory
\fC$TET_ROOT/xtest\fP.
The \s-1TCC\s0 will use this scenario file instead of the file 
\fC$TET_ROOT/xtest/tet_scen\fP
if it is passed via the \fC-s\fP option. For example
.cS
cd $TET_ROOT/xtest
tcc -c -s scenario_file [ -j journal_file ] [ -y string ] xtest all
.cE
.H 2 "Cleaning tests without using the \s-1TET\s0"
See section 11, entitled
"Building, executing and reporting tests without using the \s-1TET\s0".
.H 2 "Cleaning tests built in space-saving format"
It is possible to clean the tests in the \*(xT which were
previously built in space-saving format.
.H 3 "Cleaning tests in space-saving format using the \s-1TET\s0"
A scenario named \fClinkbuild\fP is provided in a scenario file 
named \fClink_scen\fP in the directory 
$TET_ROOT/xtest. 
This enables the \s-1TCC\s0 to clean the space-saving
executable files and remove all the required links for each test set in
each section of the \*(xT.
The -y option allows a particular space-saving 
executable and its links for a single section to be removed.
.P
Execute the command:
.cS
cd $TET_ROOT/xtest
tcc -c -s link_scen [ -j journal_file ] [ -y string ] xtest linkbuild
.cE
This command will execute the \s-1TET\s0 clean tool in the \s-1TET\s0 configuration 
variable
.SM TET_CLEAN_TOOL
(which is normally pclean),
in the top level directory of each section of the test suite.
.H 3 "Cleaning tests in space-saving format without using the \s-1TET\s0"
This section describes how to clean the space-saving
executable files for a particular section of the 
\*(xT directly without using the \s-1TET\s0.
.P
This can be simply done by calling pclean in the required directory.
For example, to clean all the space-saving executable files for
section 5 of the \*(xT, execute the command:
.cS
cd $TET_ROOT/xtest/tset/CH05
pclean
.cE
.SK
.H 1 "Building, executing and reporting tests without using the \s-1TET\s0"
.H 2 "Building tests"
An individual test set can be rebuilt
without the need to use the build mode of the \s-1TCC\s0.
This is done by executing \fCpmake\fP directly, rather than as a \s-1TET\s0 
build tool.
.P
This is a useful facility for building a single test set after a 
previous build has failed.
.P
The build configuration parameters used by \fCpmake\fP
are obtained from a file named
$TET_BUILDCONFIG, or, if TET_BUILDCONFIG is not set in your environment,
from the file named $TET_ROOT/xtest/tetbuild.cfg.
.P
The \fCpmake\fP command should be executed in the directory containing the 
source code for the test set which is to be rebuilt. For more details 
of the names of the directories containing the source code 
for the test sets, refer to appendix A.
.P
For example
.cS
cd $TET_ROOT/xtest/tset/CH05/stclpmsk
pmake
.cE
.P
No journal file is created when \fCpmake\fP is executed directly.
.P
The test set can also be rebuilt using the command
.cS
pmake Test
.cE
.P
If there is a macro version of the Xlib function, this may be rebuilt
using the command
.cS
pmake MTest
.cE
.H 2 "Executing tests"
An individual test set can be executed
without the need to use the execute mode of the \s-1TCC\s0.
This is done by executing a shell script \fCpt\fP.
.P
This is a useful facility for executing a single test set 
repeatedly when investigating a particular test result.
.P
The execution configuration parameters used by \fCpt\fP
are obtained from a file named
$TET_CONFIG, or, if TET_CONFIG is not set in your environment,
from the file named $TET_ROOT/xtest/tetexec.cfg.
.P
The \fCpt\fP command is a shell 
script, which attempts to execute the binary file named \fCTest\fP 
in the current directory. If the file \fCTest\fP is not found, 
the \fCpt\fP command attempts to execute the space-saving executable file
built in that directory.
.P
The \fCpt\fP command should be executed in the directory containing the 
test set which has been built. 
Unless you have manually installed the test set elsewhere, this will be
the directory containing the source code for the test set. For more details 
of the names of the directories containing the source code 
for the test sets, refer to appendix A.
.P
For example
.cS
cd $TET_ROOT/xtest/tset/CH05/stclpmsk
pt
.cE
.P
A \s-1TET\s0 results file is created when \fCpt\fP is executed directly.
This is a file named \fCtet_xres\fP located in the directory in which the 
test was executed.
.P
There are a number of options which may be passed to \fCpt\fP which 
alter the manner in which the test set is executed.
.P
Execute \fCpt\fP as follows:
.P
.cS
pt [ -v XT_VARIABLE_NAME ] [ -d display ] [-i IC_list ] [ -p ] [ -w ]
   [ -P ] [ -D ] [ -x debug_level ] [ -g ] [ -m ]
.cE
.P
.VL 5 0
.LI "-v XT_VARIABLE_NAME=Value"
.br
Modifies the value of the execution configuration parameter named
XT_VARIABLE_NAME, assigning it a value of \fCValue\fP.
.LI "-d display"
.br
Sets the display string to be used for the test.
.br
The default value is taken from the environment variable DISPLAY,
or, if this is not set, from the
execution configuration parameter XT_DISPLAY.
.LI "-i IC_list"
.br
The invocable components executed will be those specified 
in IC_list. 
.P
Each assertion in the \*(xT has separate test code, which is known as a
test purpose.
We have arranged that each test purpose is also
a separately invocable component,
and that the invocable component number is identical 
to the test purpose number.
.P
The invocable component list consists of one or more elements separated 
by commas. Each element is either an invocable component number 
or a range of invocable component numbers separated by a dash.
.P
This is useful for quickly executing a particular test purpose of interest
for example:
.cS
pt -i 37
.cE
This is also useful for executing all test purposes except one known 
to cause a system error.
For example:
.cS
pt -i 1-36,38-57
.cE
Note that the placement of windows used by the test suite may differ
when an earlier test purpose is not executed. It is intended that test 
purposes produce the same results regardless of window placement.
.LI -p                              
.br
This option is equivalent to setting the 
execution configuration parameter XT_DEBUG_PIXMAP_ONLY to Yes.
.LI -w                              
.br
This option is equivalent to setting the 
execution configuration parameter XT_DEBUG_WINDOW_ONLY to Yes.
.LI -P                              
.br
This option is equivalent to setting the 
execution configuration parameter XT_DEBUG_PAUSE_AFTER to Yes.
.LI -D                              
.br
This option is equivalent to setting the 
execution configuration parameter XT_DEBUG_DEFAULT_DEPTHS to Yes.
.LI "-x debug_level"
.br
This option is equivalent to setting the 
execution configuration parameter XT_DEBUG to \fCdebug_level\fP.
.LI -g                              
.br
The binary file \fCpvgen\fP will be executed instead of the binary 
file \fCTest\fP. This option should not be used, since binary 
files named \fCpvgen\fP
are only used in the development environment
at UniSoft when generating known good image files.
.LI -m                              
.br
The binary file \fCMTest\fP will be executed instead of the binary 
file \fCTest\fP. Files named \fCMTest\fP contain tests for the 
macro version of an Xlib function.
.LE
.P
Note that \fCpt\fP creates a temporary file 
\fCCONFIG\fP in the current directory
containing the configuration parameters, so write permission is required
to this file (or if no file is there, to the current directory).
.P
Note also that the binary file \fCTest\fP creates a temporary
file \fC.tmpresfd\fP in the current directory
containing the configuration parameters, so write permission is required
to this file.
.H 2 "Reporting tests"
The \s-1TET\s0 results file produced for an individual test set can be formatted
using the basic report writer \fCrpt\fP, which is described in more detail
in the section entitled "Report writer". The argument \fC-f tet_xres\fP
formats the contents of the \fCtet_xres\fP file.
.P
For convenience, a separate report writer
\fCprp\fP
is provided, which is identical to 
\fCrpt\fP,
except that the default file used is \fCtet_xres\fP 
in the current directory.
.P
This is a useful facility for quickly formatting the
results from the execution of a test set, and looking at the summary 
of the result codes for each test purpose executed.
.P
The \fCprp\fP command should be executed in the directory containing 
the \s-1TET\s0 results file named \fCtet_xres\fP.
Unless you have manually installed and executed the 
test set elsewhere, this will be the directory containing the source 
code for the test set. For more details 
of the names of the directories containing the source code 
for the test sets, refer to appendix A.
.P
For example
.cS
cd $TET_ROOT/xtest/tset/CH05/stclpmsk
prp
.cE
.H 2 "Cleaning tests"
An individual test set can be cleaned
without the need to use the clean mode of the \s-1TCC\s0.
This is done by executing \fCpclean\fP directly, rather than as a \s-1TET\s0 
clean tool.
.P
The clean configuration parameters used by \fCpclean\fP
are obtained from a file named
$TET_CLEANCONFIG, or, if TET_CLEANCONFIG is not set in your environment,
from the file named $TET_ROOT/xtest/tetclean.cfg.
.P
The \fCpclean\fP command should be executed in the directory containing the 
test set which was built. For more details 
of the names of the directories containing the source code 
for the test sets, refer to appendix A.
.P
For example
.cS
cd $TET_ROOT/xtest/tset/CH05/stclpmsk
pclean
.cE
.P
No journal file is created when \fCpclean\fP is executed directly.
.SK
.H 1 "Appendix A - Contents of \*(xR"
This section describes the contents of the directories in the \fCTET_ROOT\fP
directory which are supplied in
this release of the \*(xT. The revised \*(xT has been developed from the 
T7 \*(xT.
This section therefore also explains how the arrangement of the 
revised \*(xT compares with the T7 \*(xT.
.H 2 "tet"
.br
This contains the source files and include files needed to build
the Test Environment Toolkit (TET). The contents of the 
subdirectories are as follows:
.H 3 "tet/src"
.br
This contains the source files for
the \s-1TET\s0.
.H 3 "tet/inc"
.br
This contains the include files for
the \s-1TET\s0.
.H 3 "tet/lib"
.br
This contains the libraries and object files when the
TET has been built.
.H 3 "tet/bin"
.br
This should be empty since the 
TET utilities will be copied into 
.C $TET_ROOT/xtest/bin ,
rather than this directory, when using the modified 
Makefiles supplied with the \s-1TET\s0.
.H 3 "tet/doc"
.br
This contains the release notes and man pages for
the \s-1TET\s0.
.H 3 "tet/demo"
.br
This contains a demonstration program for
the \s-1TET\s0.
.H 2 "xtest"
.br
This contains the tests included in the revised X test suite
which are stored as a complete \s-1TET\s0 test suite. This includes all
necessary configuration files and scenario files to enable you to use
the \s-1TET\s0 following the instructions in the documentation.
.H 2 "xtest/bin"
.br
This contains commands you will need to install, configure, build 
and execute the \*(xT.
After installation, this directory 
contains shell script commands. After configuration 
and building the \*(xT, 
this directory also contains executable programs built for your system.
.H 2 "xtest/doc"
.br
This contains the documentation.
It contains this user guide, the programmers guide and the release
notes. These are supplied in \fItroff(1)\fP format requiring the \fCmm\fP 
macro package, and also in PostScript format. It also contains a 
template for error
reports and a description of how to submit them.
.P
It also contains a file 
.C paper.mm ,
which is a copy of the file
.C Xproto_verf/doc/paper.ms 
originally supplied in the T7 \*(xT, converted
to use the \fImm\fP macro package.
This file contains a paper entitled 
"An Approach to Testing X Window System Servers at a Protocol Level".
.P
This is a technical paper, which defines in outline terms the areas 
of the \*(xW server which should be tested at the X Protocol level 
rather than the Xlib level.
.P
The approach recommended in this paper, and adopted in the design of the 
T7 \*(xT, has been maintained in the revised \*(xT. The paper 
explains the choice of test cases and division of tests between 
the \*(xP and \*(xL.
.P
Before the revision of the \*(xT, UniSoft recommended that this paper should be 
left "as is". As a result, some sections of this paper are out of date in 
that they refer to development schedules for a 
previous software development project, which have now been superseded with the 
production of the revised \*(xT.
.H 2 "xtest/fonts"
.br
This contains test fonts which should be installed using the instructions 
in this user guide. It also contains a software library describing the 
fonts which is used by the tests for text drawing.
.H 2 "xtest/include"
.br
This contains include files for the software in the xtest/src and xtest/tset 
directories.
.H 2 "xtest/lib"
.br
This contains libraries and other common software which are used by the 
tests in the xtest/tset directory. The libraries are built using the 
instructions in this user guide.
.H 2 "xtest/results"
.br
This is an empty directory which is used by the \s-1TET\s0 to store journal 
files produced when executing the \*(xT.
.H 2 "xtest/src"
.br
This contains the source for the libraries and utilities. These are 
built using the instructions in this user guide.
.H 2 "xtest/tset"
.br
This contains the source for the tests for sections 2 to 10 of the 
X11R4 Xlib specifications, in directories CH02 to CH10. 
These are
built using the instructions in this user guide.
In the rest of this document, these 
are refered to as the "\*(xL".
.P
Each of the directories CH02 to CH10 contains further subdirectories
which are known as test set directories. 
Each of these contain all the test code for a single Xlib function. 
The name of the directory is derived from the name of the Xlib 
function by a scheme which is described in appendix B.
.P
So, for example for
.C XSetClipMask
we have the following:
.cS
tset/CH05/stclpmsk
tset/CH05/stclpmsk/stclpmsk.m
.cE
.P
The file
.C stclpmsk.m
is the source file, which is also known as a dot-m file.
The format of the dot-m file is described further in the "Programmers Guide".
.P
The \*(xL are designed to accomplish the following:
.P
.AL
.LI
Test the ability of the Xlib function to behave as specified in the X11R4 
Xlib specifications, in situations where no X Protocol error should 
be generated. This is tested by a series of separate tests known,
as "test purposes", each of which is designed to test a single statement 
in the Xlib specifications. The statement which is tested is contained
in an "assertion", which is also contained in the dot-m file, and 
precedes the test code for that test purpose.
.LI
Test the ability of the Xlib function to produce the expected X Protocol 
errors in specified situations. This is tested in further test purposes, 
each preceded in the dot-m file
by an assertion describing the situation which should produce the error.
.LE
.H 2 "xtest/tset/XPROTO"
.br
This contains the source for the touch tests for the X Protocol (version 11).
These are
built using the instructions in this user guide.
In the rest of this document, these 
are refered to as the "\*(xP".
.P
These tests were in a separate test suite in the T7 \*(xT, which was
located in a directory Xproto_verf. This included
separate documentation, drivers, parameter files, include files and libraries.
In the revised \*(xT, the directory XPROTO only contains the source of 
the tests - the other items are integrated within the \*(xT as described 
in this user guide.
.P
The directory XPROTO contains further subdirectories
which are known as test set directories. 
The structure of test set directories is exactly as for the \*(xL, 
described in the previous section.
.P
The \*(xP tests are designed to accomplish the following:
.P
.AL
.LI
Test the ability of the \*(xW server to accept all legal message types and 
respond appropriately.
.LI
Ensure that the server capabilities which Xlib testing depends on 
work in the simplest cases.
.LI
Test that the X server adheres to the canonical byte stream of the X Protocol,
independent of the host byte sex or compiler structure packing.
.LE
.P
For further details of the choice of test cases and division of tests between
the \*(xP and \*(xL, refer to the document entitled 
"An Approach to Testing X Window System Servers at a Protocol Level"
contained in file xtest/doc/paper.mm.
.SK
.H 1 "Appendix B - File naming scheme"
A file naming scheme has been devised which 
is for naming the directories containing dot-m files
and the dot-m files themselves. 
.P
The file naming scheme converts from an 
\*(xW name to an abbreviated name. This is done as follows:
.DL
.LI
Remove leading X.
.LI
Replace:
.DS
    Background -> Bg
    Subwindow -> Sbwn
    String -> Str
    Window -> Wdw
.DE
.LI
Remove all lowercase vowels aeiou.
.LI
Truncate to 10 chars.
We have already checked that
truncation to ten characters still gives uniqueness.
.LI
If the string before truncation ended in "16" then force truncated
    string to end in "16".
.LI
convert to lowercase.
.LI
add ".m" suffix to get name of source file containing C code, assertions
    and strategies.
.LE
.SK
.H 1 "Appendix C - Format of the \s-1TET\s0 journal file"
This appendix describes the manner in which the \*(xT uses 
some of the \s-1TET\s0 journal file facilities. The format of the \s-1TET\s0 
journal file is not fully described here - only the main features used by the 
\*(xT are described.
In a future release of the \*(xT the format is expected to
be described fully in the \s-1TET\s0 documentation.
.P
Journal files are produced by the 
\s-1TCC\s0 
during the build and execute stages.
.P
The journal file produced during the execute stage contains two basic sections:
.AL
.LI
Details of the configuration parameters and environment in which the 
tests were executed. This may also be preceded by build configuration 
parameters and/or followed by clean configuration parameters, if the 
.SM TCC
was invoked in build-execute-clean mode.
.LI
Details of the test results.
This includes the test result
codes and test information messages output by the test suite.
.LE
.P
Each line in the second section of a journal file 
is made up from three components separated by a vertical bar:
.AL
.LI
Message type. There is a unique numeric code for each message 
type which is always the first field on a line.
.LI
Message parameters. These contain serial number and similar 
information.
.LI
Message area. The format of this area is specific to the 
Message Type.
.LE
.P
An example of the second section is as follows:
.cS
10|53 /tset/CH02/vndrrls/vndrrls 13:41:12|TC Start, scenario ref 85-1, ICs {all}
15|53 1.9 1|TCM Start
520|53 0 7457 1 1|TRACE:NAME: XVendorRelease
400|53 1 1 13:41:14|IC Start
200|53 1 13:41:14|TP Start
520|53 1 7457 1 1|REPORT:XVendorRelease() returned 5000 instead of 1.
220|53 1 1 13:41:14|FAIL
410|53 1 1 13:41:14|IC End
80|53 0 13:41:15|TC End
.cE
This consists of a block of information 
for each test set executed which contains the following
lines:
.AL
.LI
Message Type 10 - Test Case Start (TC Start)
.br
A single message indicating that the Test Case Controller (the part of the 
\s-1TET\s0 which executes test sets) is about to execute a test set.
This also indicates the start of the results for this
test set (which in \s-1TET\s0 terminology is known as a test case).
This line indicates the name of the test set
obtained from the scenario file.
.LI
Message Type 15 - Test Case Manager Start (TCM Start)
.br
A single message indicating that the Test Case Manager (the part of the 
\s-1TET\s0 which calls the test purposes) has started executing.
.LI
Each assertion in the \*(xT has separate test code, which is known as a 
test purpose. 
We have arranged that each test purpose is also 
a separately invocable component,
and that the invocable component number is identical 
to the test purpose number.
For each test purpose these
lines follow:
.AL
.LI
Message Type 400 - Invocable Component Start (IC Start)
.br
The second field of the Message Parameters gives the IC number.
.LI
Message Type 200 - Test Purpose Start (TP Start)
.br
The second field of the Message Parameters gives the
number of the test purpose within the test set.
.LI
Message Type 520 - Test Case Information
.br
The second field of the Message Parameters gives the
number of the test purpose within the test set.
.br
The Message Area contains a text message output by the \*(xT -
the possible types of message are described further in 
appendix D 
"Interpreting test results" in the section entitled 
"Test information messages".
.LI
Message Type 220 - Test Purpose Result
.br
The second field of the Message Parameters gives the
number of the test purpose within the test set.
.br
The Message Area contains the test result code - the possible 
test result codes are described further in appendix D
"Interpreting test results" in the section entitled
"Test result codes".
.LI
Message Type 410 - Invocable Component End (IC End)
.br
The second field of the Message Parameters gives the IC number.
.LE
.LI
Message Type 80 - Test Case End (TC End)
.br
A single message indicating the end of the results for this
test set (which in \s-1TET\s0 terminology is known as a test case).
.LE
.SK
.H 1 "Appendix D - Interpreting test results"
This section includes information describing the significance 
of the test result codes and the accompanying 
test information messages that may appear in a \s-1TET\s0 journal file.
.H 2 "Categorisation of assertions"
The test result codes which are output for each test purpose 
are dependent on the category of the assertion.
.P
The model for the categorisation of assertions 
which is used in the \*(xT is described in POSIX.3.
.P
There are four categories of assertions described by POSIX.3 which are 
designated A, B, C and D. 
.P
If the assertion tests a conditional feature, it is categorised as type 
C or D, otherwise it is categorised as type A or B.
.P
If the assertion is classified as an "extended assertion",
it is categorised as type
B or D. Otherwise it is categorised
as type A or C and is known as a "base assertion".
.P
Tests are always required for base assertions. Tests are not required 
for extended assertions, but should be provided if possible. 
There are a number of "extended assertions" for which tests have 
been written in the \*(xT.
Extended assertions are used to describe features that may be difficult 
to test conclusively.
.P
.TS
center box;
c | c | c.
	Base Assertion	Extended Assertion
_
Required Feature	A	B
_
Conditional Feature	C	D
.TE
.H 2 "Test result codes"
The following test result codes may be found within the \s-1TET\s0 journal
file. These will be found in Test Purpose Result lines with Message Type 220
(described in appendix C).
.P
The reason for any 
result codes 
.SM NORESULT , 
.SM UNRESOLVED 
and 
.SM UNINITIATED 
should be determined and resolved.
.VL 15 0
.LI \s-1PASS\s0
The implementation passed the test for the corresponding assertion.
.LI \s-1FAIL\s0
The implementation failed the test for the corresponding assertion.
.LI \s-1UNRESOLVED\s0
The test for the corresponding assertion commenced, but was 
unable to establish the required conditions to complete all 
required stages of the test. 
The reasons for this should be investigated
and if necessary the test rerun.
.P
In some tests, reliance is made on the successful behaviour of another 
area of the \*(xW. Where this reliance is made, and that area of 
the \*(xW does not behave as expected, a result code 
.SM UNRESOLVED 
may occur. The test information messages 
should indicate the area of the underlying problem. It may be 
necessary to look at the test results for that area
first and investigate and resolve the underlying problem
before re-running the 
.SM UNRESOLVED 
tests.
.P
Tests which give a result code of UNRESOLVED and the message "Path check error"
normally contain programming errors. The test reached the point at which a PASS
result would be assigned, but the number of check points passed 
in executing the test code differs from the expected number.
.P
Tests which give a result code of UNRESOLVED and the message 
"No CHECK marks encountered"
may be due to programming errors. 
The test reached the point at which a PASS
result would be assigned, but no check points had been passed.
This can also occur when you execute the tests using debug options.
For example, the message occurs 
when you execute tests which normally loop over windows
and pixmaps and set 
.SM XT_DEBUG_PIXMAP_ONLY=Yes 
or 
.SM XT_DEBUG_WINDOW_ONLY=Yes
or 
.SM XT_DEBUG_DEFAULT_DEPTHS=Yes
or
.SM XT_DEBUG_VISUAL_IDS=Yes .
.LI \s-1NOTINUSE\s0
Although there is an assertion within the test set, there is no
specific test provided for the assertion. This might be because 
the assertion is tested adequately as part of the test for another
assertion, or because the assertion has been automatically included
into a test set in which it is not applicable.
.P
In either case, tests which report the result code NOTINUSE do not 
need to be investigated further.
.LI \s-1UNSUPPORTED\s0
This result code may only be used for assertions in category C or D
(conditional assertions).
.P
The implementation does not support some optional feature of 
the \*(xW, which is needed to test the 
corresponding assertion. In this case, the assertion will normally
make clear what optional feature is required, and there will be 
an accompanying test information message describing the feature
which was found to be unsupported.
.LI \s-1UNTESTED\s0
This result code may only be used for assertions in category B or D
(extended assertions).
.P
The implementation could not be conclusively tested to determine 
the truth of the corresponding assertion.
.P
Note that this does not mean that no testing was performed 
in the \*(xT. There are a number of "extended assertions"
for which we have provided tests where possible (to test some likely
problem areas, for example).
.LI \s-1UNINITIATED\s0
The test for the corresponding assertion could not commence due to
a problem in an earlier test purpose or an initialisation routine.
.P
Tests which produce this result code should be resolved as for
those reporting 
.SM UNRESOLVED .
.LI \s-1NORESULT\s0
Each test purpose should output a test result code before 
completing.
This special result code will be inserted by the \s-1TET\s0 in the journal 
file, if the test purpose
did not output a test result code. This indicates
a major fault during the execution of the test set
which should be investigated.
.LI \s-1WARNING\s0
The implementation passed the test for the corresponding assertion.
Whilst the behaviour of the implementation was found to be 
acceptable,
it behaves in a manner which is not recommended in the 
X11 specification
on which the assertion is based. 
.LI \s-1FIP\s0
The contents of the journal file must be examined by hand 
to determine whether the 
implementation passed the test for the corresponding assertion.
This is used for testing functions which produce 
output whose correctness cannot be easily determined automatically
by the test suite.
.LE
.H 2 "Test information messages"
There are four types of test information messages which are output
by the \*(xT. Each one results in a \s-1TET\s0 journal file line 
with Message Type "Test Case Information" (520), and with
the Message Area beginning with one of the following keywords:
.VL 15 0
.LI \s-1REPORT\s0
This keyword is used to report
the reason for any test result codes whch are other than 
.SM PASS .
A warning message is printed by the report 
writer \fCrpt\fP, if a test information message of type 
.SM REPORT
is given in a test purpose which produced a test result code 
.SM PASS .
.LI \s-1CHECK\s0
This keyword is used to record the passing of a particular 
checkpoint in the test suite code. These messages contain 
the checkpoint number within the test purpose, and the line 
number within the source code.
.P
These messages are not output
to the journal file if the execution configuration parameter
.SM XT_OPTION_NO_CHECK 
is set to Yes. 
This option can reduce the size
of the journal file considerably.
.LI \s-1TRACE\s0
This keyword is used for any messages describing the state of the 
test being executed which are not failure messages.
.P
When running the \*(xP, messages with this keyword are output to 
the journal file, to
describe briefly the interaction between the X server and the test program.
.P
These messages are not output 
to the journal file, if the execution configuration parameter
.SM XT_OPTION_NO_TRACE 
is set to Yes.
This option can reduce the size
of the journal file considerably.
.LI \s-1DEBUG\s0
This keyword is used for debug messages
inserted during the development of the \*(xT.
.P
When running the \*(xP, messages with this keyword
are output to the journal file, when the debug level is greater than zero, to
describe in detail the interaction between the X server and the test program.
This includes the contents of requests, replies and events.
.P
This is output if the value of the
execution configuration parameter 
.SM XT_DEBUG
is greater than or equal to the level of the debug message.
.SM XT_DEBUG
may be set from 0 to 3.
.LE
.SK
.H 1 "Appendix E - Outline of Test Environment Toolkit"
The "Test Environment Toolkit" 
is a software tool developed by X/Open\*F,
.FS
X/Open is a trademark of the X/Open Company, Ltd. in the U.K. and
other countries.
.FE
UNIX International (UI)\*F,
.FS
UI is a trademark of UNIX International.
.FE
and the Open Software Foundation (OSF)\*F.
.FS
Open Software Foundation, OSF and OSF/1
are trademarks of the Open Software Foundation, Inc.
.FE
The project which produced this software and the 
associated interface specifications was also known as Project Phoenix.
.P
The \s-1TET\s0 consists of a user interface program known as the Test Case
Controller (\s-1TCC\s0). This enables test software to be built and executed.
The \s-1TCC\s0 uses configuration files to specify the environment
for both the build and execute operations. The \s-1TCC\s0 also uses a 
scenario file to control which tests to build or execute.
.P
The \s-1TCC\s0 produces a journal file which is intended to
be formated by a test suite specific report writing program.
.P
The \s-1TET\s0 also includes an Application Programming Interface (API)
Part of the API is the Test Case Manager (TCM).
This includes a 
.B main()
function which calls user supplied test functions.
The
API also includes a library of functions to manage the test 
functions and perform output operations to the journal file
in a structured fashion.
.P
Since the developers of the \s-1TET\s0 have indicated a commitment to
develop software test suites that execute within this 
environment, the \s-1TET\s0 can be seen as an emerging de facto standard
environment for test suite execution.
.P 
During stage one of the \*(xT development project we
identified that the \s-1TET\s0 provides features which are
required by the revised test suite.
.P
For this reason we have developed the revised test suite
within the \s-1TET\s0 environment, 
and supplied a copy of the \s-1TET\s0 with the revised test suite. 
.P
Release 1.9 of the \s-1TET\s0 was issued by the
developers during March 1992,
and is included in this release of the \*(xT.
The software is complete
in that the functionality is stable and the implementation
agrees with the \s-1TET\s0 specification.
Documentation including
release notes and 
\fCman\fP pages for the \s-1TET\s0 utilities, are included in
this release of the \*(xT.
However, this release does not contain a Programmers Guide or Users Guide.
These are under development by UNIX International, 
but are not complete at the time of this
release, and so are not part of the current version of the \s-1TET\s0.
.SK
.H 1 "Appendix F - Glossary"
.VL 4 0
.LI "assertion"
.br
A statement of functionality for an 
.I element
of the \*(xW,
phrased such that it will be 
.B true 
for a system conforming to the \*(xW specifications.
An example would be a 
.I "test description"
phrased according to the requirements of POSIX.3.
.LI "assertion test"
.br
Synonymous with 
.IR "test purpose" .
.LI "base assertion"
.br
An 
.I assertion
for which a test suite must provide an 
.IR "assertion test" .
Every assertion that is not an extended assertion is a base assertion.
.LI "element"
.br
A particular \*(xW interface 
such as an Xlib function, header file or X11 Procotol.
.LI "extended assertion"
.br
An 
.I assertion
for which a test suite is not required to provide an
.IR "assertion test" .
An 
.I "assertion test"
should still be provided if possible.
.P
Reasons why a test suite is not required to provide a test are given in
appendix A of the Programmers Guide.
.LI "POSIX.1"
.br
Part one of the IEEE POSIX 1003 standards, the document\(dg
entitled 
\fISystem Application Program Interface (API) [C language]\fR.
Also known as P1003.1.
.LI "POSIX.3"
.br
Part three of the IEEE POSIX 1003 standards, the document\(dg
.FS \(dg
Obtainable from Publication Sales, IEEE\ Service\ Center, P.O.\ Box\ 1331,
445\ Hoes\ Lane, Piscataway, NJ\ 08854-1331, (201)\ 981-0060
.FE
entitled 
\fITest Methods for Measuring Conformance to POSIX\fR.
Also known as P1003.3.
.LI "Project Phoenix"
.br
Synonymous with
.SM TET .
.LI SVID
.br
System V Interface Definition.
.LI TCC
.br
The Test Case Controller. This is part of the 
.SM TET .
This is a user interface program which enables the test software to be 
executed. See appendix E for more details.
.LI TCM
.br
The Test Case Manager. This is part of the 
.SM TET .
This is an object file containing a 
.B main()
function which calls user supplied test functions.
See appendix E for more details.
.LI "TET"
.br
The "Test Environment Toolkit". This is a software tool which provides a 
framework within which tests may be developed and executed.
More information is given in appendix E.
.LI "test case"
.br
Synonymous with
.IR "test set".
.LI "test description"
.br
The description of a particular test 
to be performed on an 
.IR element .
This is presented in functional terms and 
describes precisely what aspect of the \*(xW is to be tested for that 
.I element .
An 
.I assertion 
is an example of a 
.IR "test description" ,
but the reverse is not the case.
.LI "test program"
.br
Synonymous with 
.IR "test set" .
.LI "test purpose"
.br
The software which tests the conformance of an implementation of the \*(xW
to an 
.IR assertion .
.LI "test set"
.br
The software containing all the 
.I "test purposes"
for an 
.IR "element" .
.LI "test strategy"
.br
A description of the design and method used to implement a 
.IR "test purpose" . 
This should say how a
.I "test purpose"
is implemented rather than what feature is being tested.
.LI XPG
.br
The X/Open Portability Guide.
.LI "\*(xL"
.br
These are the tests for sections 2 to 10 of the 
X11R4 Xlib specifications.
They are stored in subdirectories of the directories \fCCH02\fP to \fCCH10\fP
(which are to be found in the directory \fC$TET_ROOT/xtest/tset\fP).
.LI "\*(xP"
.br
These are the touch tests for the X Protocol (version 11).
They are stored in subdirectories of the directory \fCXPROTO\fP 
(which is to be found in the directory \fC$TET_ROOT/xtest/tset\fP).
.LE
.TC