rws@EXPO.LCS.MIT.EDU (Bob Scheifler) (12/21/89)
The tool is on the Test Suite tape. Here's info on the tape, followed by some man pages. The Alpha release of the X Testing Consortium's X Test Suite is now available via anonymous ftp to expo.lcs.mit.edu (18.30.0.212), in the directory /pub/XTEST/, as a split compressed tar file. The distribution is approximately 36Mb uncompressed. The suite can also be ordered from the MIT Software Center. The suite is available on one 2400ft, 1600bpi 9-track magnetic reel to reel tape written in UNIX tar format. No other distribution format is available from MIT. The tape contains source code and is distributed with a hardcopy of the documentation. To obtain a copy of the X Test Suite, please send a check drawn on a U.S. bank payable to the "Massachusetts Institute of Technology" for US $200 to: MIT Software Center Bldg. E32-300 28 Carleton Street Cambridge, MA 02139 Please send wire transfers to: First National Bank of Boston 100 Federal Street Boston, MA 0211) Acct #51463306 Reference: (your company name)M.I.T. Technology Licensing Office Please send a shipping address with your order. P.O. Boxes are undeliverable via UPS. If you have ordering questions, you can call the X Hotline at (617) 258-8330. The X Testing Consortium was formed (prior to the formation of the MIT X Consortium) to develop code suitable for testing the correctness and robustness of vendor implementations of the X Window System. This release of the test suite contains the following components: 1. Protocol Sanity Tests. These test the server's basic ability to accept all legal message types and respond appropriately, test aspects which cannot be tested adequately from Xlib, and test basic server functionality that the Xlib tests depend on. 2. Xlib Tests. Comprehensive tests for most routines and macros in the Xlib interface, testing both Xlib and the server. Includes pixel validation of graphics requests. 3. Xlib Test Specifications. Informal written specifications of what the Xlib Tests should do. 4. Volume/Stress Tests. Tests server robustness with high data load and high computational load sustained over both short and long periods of time, and provides a framework for adding additional tests. 5. Client Exerciser. Utilities for recording and playing back scripts of user actions (keyboard and pointer events), for the purpose of testing clients. The utilities make use of the Input Synthesis Extension (distributed as part of X11 Release 3 from MIT). 6. Graphics Benchmark. Yet another graphics benchmark tool. 7. Interactive Xlib. A test program which will read and execute Xlib functions and macros, both interactively and from input control files. 8. Gbench. A graphics benchmark tool from Stanford. This was not developed by the X Testing Consortium, it is simply included here as another utility. This is an ALPHA release of the test suite. It is not complete, and there is no particular guarantee that any problems reported by this suite are really bugs in your Xlib or server implementation, they may well be bugs in the test suite itself. The contents of this tape are not endorsed as any form of standard by the X Consortium. This test suite is the result of considerable work by numerous people in the companies making up the X Testing Consortium, and we are indebted to them. MIT was not directly involved in the development of the test suite, but did meet with the X Testing Consortium on a regular basis. This release of the test suite has not gone through MIT's configuration and build process, so it may take some effort to build the suite on your machine. Although there is much work left to be done, this test suite represents an excellent beginning. With this release, the X Testing Consortium is disbanding, but the MIT X Consortium will continue the development of X testing software. .TH XTMCONVERT 1 .ad b .SH NAME xtmconvert \- convert test scripts to and from other formats .SH SYNOPSIS .B xtmconvert [\fB-s\fR] \fIfromfile\fR \fItofile\fR .SH DESCRIPTION .I Xtmconvert converts test scripts in .B internal format to or from .B summary or .B output formats. The type of conversion performed depends on the ending characters of the file names. .SS File Name Syntax The file names given to .I xtmconvert must end in ".scr", ".out", or ".sum". The first file name is the file to be converted. The second file name is the file where the results of the conversion are placed. .PP To convert from .B internal format to .B output format, use: .PP .RS xtmconvert testscript.scr testscript.out .RE .PP To convert from .B internal format to .B summary format, use: .PP .RS xtmconvert testscript.scr sumscript.sum .RE .PP To convert from .B output format to .B internal format, use: .PP .RS xtmconvert oldscript.out newscript.scr .RE .PP To convert from .B summary format to .B internal format, use: .PP .RS xtmconvert testscript.sum testscript.scr .RE .PP .PP If no file names or incorrect file names are given, .I xtmconvert will display the correct invocation syntax and terminate with a non-zero exit status value. .SS Running Xtmconvert .I Xtmconvert may be run in an X terminal emulator or on a terminal. If you run .I xtmconvert on a terminal, make sure that the .B DISPLAY environment variable is set to the name of the desired X server. .PP .I Xtmconvert uses the X server to convert between key codes and the corresponding key names. .PP If no error occurs during the conversion, .I xtmconvert will terminate with an exit status value of zero. If an error occurs during the conversion, .I xtmconvert will terminate with a non-zero exit status value. .PP If the .B -s option is used then any recorded image data or checksums contained in the test script are left out of the converted test script. This is useful if you are moving test scripts to a different machine, since the image data or checksums are almost always machine-specific. .SS Contents of a Test Script All test scripts must contain a version number. The version number is checked when the test script is converted to help deal with future changes to the test script format. If a test script does not have a version number or has a version number that .I xtmconvert does not know how to convert, .I xtmconvert will terminate with a non-zero exit status. .PP A test script may contain four types of input actions: .TP .B key or mouse button presses or releases This input action contains which key or mouse button was pressed or released. .TP .B relative pointer motions This input action contains the relative offset from the current pointer position to the new pointer position. This input action has a maximum range of 15 pixels from the current pointer position. If the pointer must move further than 15 pixels then a pointer jump input action must be used. .TP .B pointer jumps This input action contains x and y coordinates for the pointer to move to. The coordinates are zero in the upper left corner of the screen, the x coordinate increases horizontally from left to right, and the y coordinate increases vertically from top to bottom. .TP .B time delays This input action contains the amount of time to delay before going on to the next input action. .PP Each input action has a time delay before the input action is performed. Except for the time delay input action, the input actions have a limited range of 0 to 65535 milliseconds (approximately one minute). The time delay input action has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). .PP A test script may contain four types of requests for verification of image data from the display: .TP .B mouse The image data to be verified comes from the window that is a child of the root window and that contains the mouse (pointer) at the time that the request occurs. .TP .B screen The image data to be verified comes from the entire screen. .TP .B top The image data to be verified comes from the window that is a child of the root window and that is the "top" window (as defined by the X server) at the time that the request occurs. .TP .B partial The image data to be verified comes from a partial window specified by the user. .PP The method of image data verification depends on the checksum mode. If the checksum mode is turned off when the request occurs, the image data is verified by comparing the image data with image data stored in the test script. If the checksum mode is turned on when the request occurs, the image data is verified by comparing a checksum computed from the image data with a checksum stored in the test script. .PP A test script may contain checksum mode commands that turn the checksum mode on or off. The checksum mode is turned off at the start of each test script. .PP To change the checksum mode for all or part of an existing test script, convert the test script to .B output format, edit the .B output format of the test script to add or modify any desired checksum mode commands, and convert the test script back to .B internal format. .PP A test script may also contain comments, which have no effect on the execution of a test script. .SS Internal Format The data in the .B internal format of the test script is organized in a way that is convenient for .I xtmrecord(1) and .I xtmexecute(1) to use, but is not easily readable by human beings or portable across different computer systems. .PP The .B internal format of the test script may be created by .I xtmconvert or .I xtmrecord(1) and is the required format of the test script if it is to be played back by .I xtmexecute(1). .PP The .B internal format of the test script contains all of the data in the test script. It is stored in a file whose name ends in ".scr". .PP A test script in .B internal format with no recorded image data for the image data comparison requests would have to be updated (by running .I xtmexecute(1) with the .B -u option) before being used as a test script. .SS Output Format The data in the .B output format of the test script is organized in a way that is more portable across different computer systems. The data is possible for a human being to understand, but the level of detail tends to obscure what the test script is doing. .PP The .B output format of the test script may be created by .I xtmconvert or by an editor, but if you want to create a test script with an editor it is much easier to create a test script in the .B summary format. .PP The .B output format of the test script is stored in a file whose name ends in ".out". .PP The .B output format of the test script contains all of the data in the test script. When converting between .B internal format and .B output format all of the information in the test script is preserved. .PP When .I xtmconvert is converting from .B internal format to .B output format the version number is converted to a line containing: .PP .RS .B VERSION [\fIversionnumber\fB]\fR .RE .PP The .I versionnumber value holds the current version number of the test script. .PP When .I xtmconvert is converting from .B internal format to .B output format each input action is converted to a line containing the following fields: .TP .B input action name This field contains the name of the input action. The contents of this field is described for each type of input action below. .TP \fBDEV [\fIdevicenumber\fB]\fR The .I devicenumber value holds the value for the device that generated the input action. This is a provision for future support of multiple (distinguishable) devices. It should be 0 for most X servers. For most Hewlett Packard X servers it will have the following values: .RS .RS .sp .TP 0 Pointer jump input actions generated by .I xtmrecord(1) or the .I Input Synthesis extension. These may occur at several places in the test script. .TP 1 Pointer jump and relative pointer motion input actions generated by the X server. Also mouse button press or release input actions. .TP 3 Key press or release input actions. .RE .RE .TP .B input action specific information This field contains information specific to the type of the input action. The contents of this field are described for each type of input action below. .TP \fBTIME (ms) [\fItimedelay\fB]\fR The .I timedelay value holds the time delay value associated with the input action. .TP \fBCOUNT [\fIcount\fB]\fR The .I count value holds an input action counter to help make it easier to tell how many input actions are in the test script. .IP This field must be present when converting a test script from .B output format to .B internal format, but the .I count value is ignored. This allows someone to modify the input actions in a test script in .B output format without later causing an error while converting the test script back to .B internal format. .PP A key press input action has an input action name of .B KEY_DOWN and puts: .PP .RS \fBKEY [\fIkeyname\fB]\fR .RE .PP in the input action specific information field. .PP A key release input action has an input action name of .B KEY_UP and puts: .PP .RS \fBKEY [\fIkeyname\fB]\fR .RE .PP in the input action specific information field. .PP The .I keyname value is the X server's name for that key on the X server's keyboard. It may be composed of a single character for common keys (such as .B a for the key labled `A' on the keyboard), or it may be composed of multiple characters for other keys (such as .B bracketleft for the key labeled `[' on the keyboard). .PP The mouse buttons do not have a key name defined for them by the X server. .I Xtmconvert uses .B Button1, Button2, Button3, and so forth as the equivalent of the key name for the mouse buttons. Otherwise, the mouse button input actions are treated the same as the key input actions. .PP A pointer jump input action has an input action name of .B JUMP and puts: .PP .RS \fBX [\fIxpixloc\fB] Y [\fIypixloc\fB]\fR .RE .PP in the input action specific information field. The .I xpixloc and .I ypixloc values are the x and y coordinates of the pixel that the pointer will move to. .PP A relative pointer motion input action has an input action name of .B MOVE and puts: .PP .RS \fBX [\fIxpixmov\fB] Y [\fIypixmov\fB]\fR .RE .PP in the input action specific information field. The .I xpixmov and .I ypixmov values are the relative offsets from the current pointer position to the new pointer position. .PP A time delay input action has an input action name of .B TIME and puts nothing in the input action specific information field. Also, a time delay input action does not have a device field. .PP Requests for verification of image data from the display are converted to six header lines containing the following fields: .TP \fB MATCH #\fImatchnum\fR The .I matchnum value holds an counter of the number of requests for image data verifications in the test script. It will start at 1 for the first request, and may range up to 99 (the maximum number of requests permitted in one test script). .TP \fB TYPE[\fItypeletter\fB]\fR The .I typeletter value holds a letter describing the type of the request: .RS .TP .B m The request is to verify the window that is a child of the root window and that contains the mouse at this point in the test script. .TP .B p The request is to verify a user-specified partial window on the X server. .TP .B s The request is to verify the entire screen on the X server. .TP .B t The request is to verify the window that is a child of the root window and that is the "top" window (as defined by the X server) at this point in the test script. .RE .TP \fB REP[\fIrepcount\fB]\fR The .I repcount value holds the number of times to retry the image data verification before deciding that the verification has failed. .TP \fB INTV[\fIinterval\fB]\fR The .I interval value holds the amount of time to wait (in milliseconds) before each retry. .TP \fB CNT[\fIcount\fB]\fR The .I count value holds the number of bytes of compressed image data for this request. .TP \fB CM[\fIchecksummode\fB]\fR The .I checksummode value holds the checksum mode that was in effect for this request. .TP \fB S#\fIscreennum\fR The .I screenum value holds the number of the screen that contained the image data. .TP \fB WX[\fIwindowxorg\fB]\fR The .I windowxorg value holds the x coordinate of the upper left corner of the window that contained the image data. .TP \fB WY[\fIwindowyorg\fB]\fR The .I windowyorg value holds the y coordinate of the upper left corner of the window that contained the image data. .TP \fB WW[\fIwindowwidth\fB]\fR The .I windowwidth value holds the width of the window that contained the image data (in pixels). .TP \fB WH[\fIwindowheight\fB]\fR The .I windowheight value holds the height of the window that contained the image data (in pixels). .sp .TP \fB BW[\fIborderwidth\fB]\fR The .I borderwidth value holds the border width of the window that contained the image data (in pixels). .TP \fB WN"\fIwindowname\fB"\fR The .I windowname value holds the name of the window that contained the image data. .TP \fB X[\fIxpixloc\fB]\fR The .I xpixloc value holds the window-relative x coordinate of the image data. .TP \fB Y[\fIypixloc\fB]\fR The .I ypixloc value holds the window-relative y coordinate of the image data. .TP \fB W[\fIwidth\fB]\fR The .I width value holds the width of the image data (in pixels). .TP \fB H[\fIheight\fB]\fR The .I height value holds the height of the image data (in pixels). .TP \fB D[\fIdepth\fB]\fR The .I depth value holds the depth of the image data. .TP \fB F[\fIformat\fB]\fR The .I format value holds the format of the image data. .TP \fB XOFF[\fIxoffset\fB]\fR The .I xoffset value holds the horizontal offset of the image data. .TP \fB BO[\fIbyteorder\fB]\fR The .I byteorder value holds the byte order of the image data. .TP \fB BU[\fIbitmapunit\fB]\fR The .I bitmapunit value holds the bitmap unit of the image data. .TP \fB BBO[\fIbitmapbitorder\fB]\fR The .I bitmapbitorder value holds the bitmap bit order of the image data. .TP \fB BP[\fIbitmappad\fB]\fR The .I bitmappad value holds the bitmap pad boundary of the image data. .sp .TP \fB BPL[\fIbytesperline\fB]\fR The .I bytesperline value holds the number of bytes for each line (padding included) of the image data. .TP \fB BPP[\fIbitsperpixel\fB]\fR The .I bitsperpixel value holds the number of bits for each pixel of the image data. .TP \fB VC[\fIvisualclass\fB]\fR The .I visualclass value holds the type of the color map of the window that contained the image data. .TP \fB RM[\fIredmask\fB]\fR The .I redmask value holds the red mask for the image data. .TP \fB GM[\fIgreenmask\fB]\fR The .I greenmask value holds the green mask for the image data. .TP \fB BM[\fIbluemask\fB]\fR The .I bluemask value holds the blue mask for the image data. .TP \fB BPR[\fIbitsperrgb\fB]\fR The .I bitsperrgb value holds the log (base 2) of the number of distinct color values in the image data. .TP \fB CE[\fIcolormapentries\fB]\fR The .I colormapentries value holds the number of color entries in the color map of the window that contained the image data. .TP \fB C[\fIncolors\fB]\fR The .I ncolors value holds the number of color structures used to describe the color entries in the color map of the window that contained the image data. .PP The header lines will be followed by one line for each color map entry containing the following fields: .TP \fB PIXEL[\fIpixelnumber\fB]\fR The .I pixelnumber value holds the color map entry number for this color. .TP \fB RED[\fIredvalue\fB]\fR The .I redvalue value holds the red value for this color. .TP \fB GREEN[\fIgreenvalue\fB]\fR The .I greenvalue value holds the green value for this color. .TP \fB BLUE[\fIbluevalue\fB]\fR The .I bluevalue value holds the blue value for this color. .TP \fB FLAGS[\fIflags\fB]\fR The .I flags value holds the flags value for this color. .PP If the checksum mode if off, the color map entry lines will be followed by many lines containing the image data in a (run length encoded) compressed form. The image data is compressed by counting the number of bytes of the same value in sequence in the image data (as read from the X server). The count is output as two ascii characters representing hexadecimal digits. The byte value follows as two more ascii characters representing hexadecimal digits. This is repeated until all of the image data is encoded. .PP If the checksum mode is on or the image data has been stripped from the test script, only the header lines will remain. The image data is often stripped when moving a test script from one type of computer to another, since it is machine-dependent. .PP A checksum mode command is converted to a line containing: .PP .RS .B CHECKSUMS \fIchecksummode\fR .RE .PP The .I checksummode value holds the current checksum mode of the test script (either \fBOFF\fR or \fBON\fR). .PP A comment is converted to a line containing: .PP .RS .B COMMENT \fIcomment\fB .RE .PP The .I comment may contain any printable characters except a ">". It should be limited to less than 70 characters. .SS Summary Format The data in the .B summary format of the test script is organized in a way that is easier for a human being to understand and edit. .PP The .B summary format of the test script (except for image verfication data) is stored in a file whose name ends in ".sum". The image verification data is stored in multiple files, one file for each image data verification request in the test script. .PP If the checksum mode if off, the recorded image data is stored in .I xwd(1) format in a fids the y coordinate of the upper left corner of the window that contained the image data. .TP \fB WW[\fIwindowwidth\fB]\fR The .I windowwidth value holds the width of the window that contained the image data (in pixels). .TP \fB WH[\fIwindowheight\fB]\fR The .I windowheight value holds the height of the window that contained the image data (in pixels). .sp .TP \fB BW[\fIborderwidth\fB]\fR The .I borderwidth value holds the border width of the window that contained the image data (in pixels). .TP \fB WN"\fIwindowname\fB"\fR The .I windowname value holds the name of the window that contained the image data. .TP \fB X[\fIxpixloc\fB]\fR The .I xpixloc value holds the window-relative x coordinate of the image data. .TP \fB Y[\fIypixloc\fB]\fR The .I ypixloc value holds the window-relative y coordinate of the image data. .TP \fB W[\fIwidth\fB]\fR The .I width value holds the width of the image data (in pixels). .TP \fB H[\fIheight\fB]\fR The .I height value holds the height of the image data (in pixels). .TP \fB D[\fIdepth\fB]\fR The .I depth value holds the depth of the image data. .TP \fB F[\fIformat\fB]\fR The .I format value holds the format of the image data. .TP \fB XOFF[\fIxoffset\fB]\fR The .I xoffset value holds the horizontal offset of the image data. .TP \fB BO[\fIbyteorder\fB]\fR The .I byteorder value holds the byte order of the image data. .TP \fB BU[\fIbitmapunit\fB]\fR The .I bitmapunit value holds the bitmap unit of the image data. .TP \fB BBO[\fIbitmapbitorder\fB]\fR The .I bitmapbitorder value holds the bitmap bit order of the image data. .TP \fB BP[\fIbitmappad\fB]\fR The .I bitmappad value holds the bitmap pad boundary of the image data. .sp .TP \fB BPL[\fIbytesperline\fB]\fR The .I bytesperline value holds the number of bytes for each line (padding included) of the image data. .TP \fB BPP[\fIbitsperpixel\fB]\fR The .I bitsperpixel value holds the number of bits for each pixel of the image data. .TP \fB VC[\fIvisualclass\fB]\fR The .I visualclass value holds the type of the color map of the window that contained the image data. .TP \fB RM[\fIredmask\fB]\fR The .I redmask value holds the red mask for the image data. .TP \fB GM[\fIgreenmask\fB]\fR The .I greenmask value holds the green mask for the image data. .TP \fB BM[\fIbluemask\fB]\fR The .I bluemask value holds the blue mask for the image data. .TP \fB BPR[\fIbitsperrgb\fB]\fR The .I bitsperrgb value holds the log (base 2) of the number of distinct color values in the image data. .TP \fB CE[\fIcolormapentries\fB]\fR The .I colormapentries value holds the number of color entries in the color map of the window that contained the image data. .TP \fB C[\fIncolors\fB]\fR The .I ncolors value holds the number of color structures used to describe the color entries in the color map of the window that contained the image data. .PP The header lines will be followed by one line for each color map entry containing the following fields: .TP \fB PIXEL[\fIpixelnumber\fB]\fR The .I pixelnumber value holds the color map entry number for this color. .TP \fB RED[\fI is a pointer jump input action. The .I xpixloc and .I ypixloc values are the x and y coordinates of the pixel that the pointer will move to. The .I timedelay value is the number of milliseconds to delay before moving the pointer. .TP .B <MOTION \fIxpixmov ypixmov timedelay\fB> This is a relative pointer motion input action. The .I xpixmov and .I ypixmov values are the relative offsets from the current pointer position to the new pointer position. The .I timedelay value is the number of milliseconds to delay before moving the pointer. .TP .B <TIME \fItimedelay\fB> This is a time delay input action. The .I timedelay value is the amount of time to delay before going on to the next input action. .PP The requests for verification of image data from the display are converted to lines containing: .TP .B <MATCH MOUSE\fR[ \fIfilename screennum windowx windowy\fR]\fB> The image verification data came from the window that was a child of the root window and that contained the mouse at the time that the request was put in the test script. .TP .B <MATCH PARTIAL\fR[ \fIfilename screennum windowx windowy\fR]\fB> The image verification data came from a user-specified partial window on the X server at the time that the request was put in the test script. .TP .B <MATCH SCREEN\fR[ \fIfilename screennum windowx windowy\fR]\fB> The image verification data came from the entire screen on the X server at the time that the request was put in the test script. .TP .B <MATCH TOP\fR[ \fIfilename screennum windowx windowy\fR]\fB> The image verification data came from the window that was a child of the root window and that was the "top" window (as defined by the X server) at the time that the request was put in the test script. .PP The name of the image verification data file associated with a particular request is placed as .I filename in the request. .PP The image verification data file holds all of the information about the image data except for the screen number and the x and y coordinates of the window containing the image data. Those values are placed in the request. .PP If there is no image verification data in the test script, then none of the optional data will be placed in the request. .PP The version number is converted to a line containing: .PP .RS .B <VERSION \fIversionnumber\fB>\fR .RE .PP The .I versionnumber value holds the current version number of the test script. .PP A checksum mode command is converted to a line containing: .PP .RS .B <CHECKSUMS \fIchecksummode\fB>\fR .RE .PP The .I checksummode value holds the current checksum mode of the test script (either \fBOFF\fR or \fBON\fR). .PP A comment is converted to a line containing: .PP .RS .B <COMMENT \fIcomment\fB> .RE .PP The .I comment may contain any printable characters except a ">". It should be limited to less than 70 characters. .PP When .I xtmconvert is converting from .B summary format to .B internal format some of the information needed for the .B internal format of the test script is not in the .B summary format of the test script. The additional information needed is taken from .I .Xdefaults variables. .SS "Example of an Output Format Test Script" .PP The .B internal format of this test script was created by recording actual user actions using .I xtmrecord(1). .PP This test script starts with the cursor on the right half of a display. It moves the cursor to the left half of the display and types "echo it worked!" followed by the "Return" key. It then moves the cursor back to the right half of the display and terminates. .PP Contrast this with the .B summary format of the same test script shown below. .PP The .B Count field was deleted from the end of the input action lines in this example to make it fit in the document. .PP .nf VERSION [1] JUMP DEV [0] X [ 547] Y [ 339] TIME (ms) [ 0] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 768] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 199] MOTION DEV [1] X [ 0] Y [ -1] TIME (ms) [ 79] MOTION DEV [1] X [ 0] Y [ -1] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 60] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ -2] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 35] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 11] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 13] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 20] MOTION DEV [1] X [ -3] Y [ -3] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -3] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -3] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -3] TIME (ms) [ 19] MOTION DEV [1] X [ -3] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -3] Y [ -1] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -3] Y [ -2] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 20] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ -2] TIME (ms) [ 20] MOTION DEV [1] X [ -2] Y [ 0] TIME (ms) [ 20] MOTION DEV [1] X [ -1] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ -2] TIME (ms) [ 27] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 32] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 39] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 40] MOTION DEV [1] X [ -1] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 39] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ -2] TIME (ms) [ 20] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ 0] Y [ -2] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ 0] TIME (ms) [ 20] MOTION DEV [1] X [ 0] Y [ -1] TIME (ms) [ 59] MOTION DEV [1] X [ -1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ -1] Y [ -1] TIME (ms) [ 19] MOTION DEV [1] X [ -2] Y [ 0] TIME (ms) [ 140] KEY_DOWN DEV [3] KEY [e] TIME (ms) [ 2429] KEY_UP DEV [3] KEY [e] TIME (ms) [ 39] KEY_DOWN DEV [3] KEY [c] TIME (ms) [ 199] KEY_UP DEV [3] KEY [c] TIME (ms) [ 60] KEY_DOWN DEV [3] KEY [h] TIME (ms) [ 79] KEY_UP DEV [3] KEY [h] TIME (ms) [ 59] KEY_DOWN DEV [3] KEY [o] TIME (ms) [ 169] KEY_UP DEV [3] KEY [o] TIME (ms) [ 80] KEY_DOWN DEV [3] KEY [space] TIME (ms) [ 439] KEY_UP DEV [3] KEY [space] TIME (ms) [ 100] KEY_DOWN DEV [3] KEY [i] TIME (ms) [ 220] KEY_UP DEV [3] KEY [i] TIME (ms) [ 99] KEY_DOWN DEV [3] KEY [t] TIME (ms) [ 329] KEY_UP DEV [3] KEY [t] TIME (ms) [ 80] KEY_DOWN DEV [3] KEY [space] TIME (ms) [ 1109] KEY_UP DEV [3] KEY [space] TIME (ms) [ 99] KEY_DOWN DEV [3] KEY [w] TIME (ms) [ 450] KEY_UP DEV [3] KEY [w] TIME (ms) [ 100] KEY_DOWN DEV [3] KEY [o] TIME (ms) [ 19] KEY_UP DEV [3] KEY [o] TIME (ms) [ 100] KEY_DOWN DEV [3] KEY [r] TIME (ms) [ 119] KEY_UP DEV [3] KEY [r] TIME (ms) [ 59] KEY_DOWN DEV [3] KEY [k] TIME (ms) [ 240] KEY_UP DEV [3] KEY [k] TIME (ms) [ 79] KEY_DOWN DEV [3] KEY [e] TIME (ms) [ 159] KEY_UP DEV [3] KEY [e] TIME (ms) [ 40] KEY_DOWN DEV [3] KEY [d] TIME (ms) [ 229] KEY_UP DEV [3] KEY [d] TIME (ms) [ 59] KEY_DOWN DEV [3] KEY [Shift_L] TIME (ms) [ 480] KEY_DOWN DEV [3] KEY [1] TIME (ms) [ 849] KEY_UP DEV [3] KEY [1] TIME (ms) [ 99] KEY_UP DEV [3] KEY [Shift_L] TIME (ms) [ 39] KEY_DOWN DEV [3] KEY [Return] TIME (ms) [ 1920] KEY_UP DEV [3] KEY [Return] TIME (ms) [ 100] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 1920] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 20] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 3] Y [ 1] TIME (ms) [ 20] MOTION DEV [1] X [ 3] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 3] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ 4] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 4] Y [ 0] TIME (ms) [ 33] MOTION DEV [1] X [ 4] Y [ 1] TIME (ms) [ 6] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 2] TIME (ms) [ 19] MOTION DEV [1] X [ 3] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 4] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 4] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 3] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 3] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 4] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 3] TIME (ms) [ 19] MOTION DEV [1] X [ 3] Y [ 4] TIME (ms) [ 20] MOTION DEV [1] X [ 3] Y [ 4] TIME (ms) [ 108] MOTION DEV [1] X [ 3] Y [ 3] TIME (ms) [ 1] MOTION DEV [1] X [ 2] Y [ 3] TIME (ms) [ 1] MOTION DEV [1] X [ 2] Y [ 1] TIME (ms) [ 12] MOTION DEV [1] X [ 1] Y [ 1] TIME (ms) [ 1] MOTION DEV [1] X [ 1] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 0] TIME (ms) [ 5] MOTION DEV [1] X [ 0] Y [ 1] TIME (ms) [ 8] MOTION DEV [1] X [ 1] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 0] Y [ 1] TIME (ms) [ 20] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 19] MOTION DEV [1] X [ 2] Y [ 2] TIME (ms) [ 20] MOTION DEV [1] X [ 2] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 0] Y [ 1] TIME (ms) [ 19] MOTION DEV [1] X [ 1] Y [ 0] TIME (ms) [ 59] TIME TIME (ms) [ 1179] MOTION DEV [1] X [ 0] Y [ 0] TIME (ms) [ 2] JUMP DEV [0] X [ 556] Y [ 357] TIME (ms) [ 0] .fi .SS "Example of a Summary Format Test Script" The .B internal format of this test script was created by recording actual user actions using .I xtmrecord(1). .PP This test script starts with the cursor on the right half of a display. It moves the cursor to the left half of the display and types "echo it worked!" followed by the "Return" key. It then moves the cursor back to the right half of the display and terminates. .PP Contrast this with the .B output format of the same test script shown above. .PP .nf <VERSION 1> <JUMP 472 283 2217> echo <space> it <space> worked <KEY_DOWN Shift_L> 1 <KEY_UP Shift_L> <Return> <TIME 10690> <JUMP 556 357 2811> <TIME 1179> <JUMP 556 357 2> .fi .SS X Server Key Names This is a table of key names used by most Hewlett Packard X servers. Other X servers should use most of the same key names, with additions or deletions for keys not found on Hewlett Packard X servers. .PP These are the single-character key names: .PP .RS .nf 1234567890 .sp abcdefghijklmnopqrstuvwxyz .fi .RE .PP These are the multi-character key names: .PP .RS .nf Key Name Corresponding Key Label \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- backslash "\\" bracketleft "[" bracketright "]" comma "," equal "=" minus "-" period "." quoteleft "`" quoteright "'" semicolon ";" slash "/" space " " (generated by the space bar) BackSpace "Back space" Break "Break" Cancel "Stop" Caps_Lock "Caps" Clear "Clear display" ClearLine "Clear line" Control_L "CTRL" DeleteChar "Delete char" DeleteLine "Delete line" Down (the downward-pointing arrow) Escape "ESC" Execute "Enter" Home (the upper-left-pointing arrow) InsertChar "Insert char" InsertLine "Insert line" Left (the left-pointing arrow) Menu "Menu" Meta_L "Extend char" (left-hand) Meta_R "Extend char" (right-hand) Next "Next" Prior "Prev" Return "Return" Right (the right-pointing arrow) Select "Select" Shift_L "Shift" (left-hand) Shift_R "Shift" (right-hand) System "System" Tab "Tab" Up (the upper-pointing arrow) F1 "f1" F2 "f2" F3 "f3" F4 "f4" F5 "f5" F6 "f6" Key Name Corresponding Key Label \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- F7 "f7" F8 "f8" KP_0 "0" (on the keypad) KP_1 "1" (on the keypad) KP_2 "2" (on the keypad) KP_3 "3" (on the keypad) KP_4 "4" (on the keypad) KP_5 "5" (on the keypad) KP_6 "6" (on the keypad) KP_7 "7" (on the keypad) KP_8 "8" (on the keypad) KP_9 "9" (on the keypad) KP_Add "+" (on the keypad) KP_Decimal "." (on the keypad) KP_Divide "/" (on the keypad) KP_Enter "Enter" (on the keypad) KP_F1 (leftmost blank key) KP_F2 (second from the left blank key) KP_F3 (second from the right blank key) KP_F4 (rightmost blank key) KP_Multiply "*" (on the keypad) KP_Separator "," (on the keypad) KP_Subtract "-" (on the keypad) KP_Tab "Tab" (on the keypad) .fi .RE .SS .Xdefaults Variable Usage .I Xtmconvert recognizes the following .I .Xdefaults variables (shown with their default values): .PP .RS xtmconvert.MatchRetries: 3 .RE .RS xtmconvert.RetryInterval: 5000 .RE .RS xtmconvert.KeyDevice: 0 .RE .RS xtmconvert.PointerDevice: 0 .RE .RS xtmconvert.KeyInterval: 50 .RE .RS xtmconvert.StrokeInterval: 50 .RE .PP All of these variables are only used when converting a .B summary format test script to an .B internal format test script. .PP The .I MatchRetries variable controls the number of times a failing image data verification will be retried when the test script is executed using .I xtmexecute(1). It has a range of 0 to 32767 retries. .PP The .I RetryInterval variable controls the interval in milliseconds between each retry when the test script is executed using .I xtmexecute(1). It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). .PP The .I KeyDevice variable holds the value for the keyboard device. This is a provision for future support of multiple (distinguishable) keyboard devices (the default is 3 for Hewlett Packard X servers). It has a range of 0 to 14. .PP The .I PointerDevice variable holds the value for the pointer (mouse) device. This is a provision for future support of multiple (distinguishable) pointer devices (the default is 1 for Hewlett Packard X servers). It has a range of 0 to 14. .PP The .I KeyInterval variable holds the time delay before each key transition. It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). .PP The .I StrokeInterval variable holds the time delay after the down transition of a key and before the up transition of the same key in a key stroke. It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). .SH SEE ALSO xtmrecord(1), xtmexecute(1), xwd(1). .SH COPYRIGHT .PP Copyright 1986, 1987, 1988, 1989 by Hewlett-Packard Corporation .PP Copyright 1986, 1987, 1988, 1989 by the Massachusetts Institute of Technology .PP Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. .PP Hewlett-Packard and M.I.T. make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. .PP This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California. .TH XTMEXECUTE 1 .ad b .SH NAME xtmexecute \- test script execution (playback) tool .SH SYNOPSIS .B xtmexecute [\fB-d\fR] [\fB-u\fR|\fB-c\fR] [\fB-t\fR [\fB+\fR|\fB-\fR|\fB/\fR|\fB*\fR] \fIfactor\fR] \fIfilename\fR .br .SH DESCRIPTION .I Xtmexecute plays back one or more test scripts created by .I xtmrecord(1) or by .I xtmconvert(1). The test scripts must contain a record of which keys and mouse buttons were pressed and released, where the mouse was moved to, and what the time delays were before each action. The test scripts may also contain requests for verification of image data from the display. .SS File Name Syntax If the .B \-d option is used, then .I filename must be the name of a directory. Otherwise .I filename must end in ".scr". Thus: .PP .RS xtmexecute -d testdir .RE .PP will play back all of the test scripts in .I testdir and any directories below .I testdir, and .PP .RS xtmexecute testscript.scr .RE .PP will play back a test script .I testscript.scr. If no file name or an incorrect file name is given, .I xtmexecute will display the correct invocation syntax and terminate with a non-zero exit status but without creating an error file. .SS Running Xtmexecute .I Xtmexecute may be run in an X terminal emulator window or on a terminal. If you run .I xtmexecute on a terminal, make sure that the .SM .B DISPLAY environment variable is set to the name of the desired X server. .PP .I Xtmexecute requires that the X server support the .I Input Synthesis extension. This extension supplies the additional capabilities needed to play back a test script. .PP .I Xtmexecute will communicate with the X server to start playing back one or more test scripts as soon as it is invoked. Several options modify how the test scripts are played back: .TP .B \-d This option allows .I xtmexecute to be used to run multiple test scripts. It causes .I xtmexecute to play back all of the test scripts in .I filename (which must be the name of a directory) followed by playing back any test scripts in directories below .I filename. .TP .B \-u This option allows a test script to be updated if the expected display image data changes. When this option is used .I xtmexecute plays back a test script normally except that instead of verifying the image data, .I xtmexecute puts information about the current image data into the test script for later use. .TP .B -c This option causes .I xtmexecute to continue to play back a test script in spite of any image data verification failures. When this option is used, an image data verification failure will cause .I xtmexecute to leave an error file, but .I xtmexecute will not terminate with a non-zero exit status because of the failure. .IP This option is mostly used when playing back multiple test scripts, so that an image data verification failure in one test script will not stop the other test scripts from being played back. .TP .B -t This option allows the user to modify the time delay associated with each action in the test scripts. The syntax for this option is the same as that of the .I ActionTiming .Xdefaults variable. Since many command interpreters use the .B * as a pattern-matching character, you may want to use the .I ActionTiming .Xdefaults variable instead of this option. .PP .I Xtmexecute will play back the actions in the test scripts in the order that the test scripts specify. .I Xtmexecute will attempt to play back the actions with the same time delays as the test scripts specify. The time delays may be longer than the test scripts specify due to delays in communication between .I xtmexecute and the X server and/or delays in the X server. .PP All test scripts contain a version number. .I Xtmexecute checks the version number when a test script is played back to help deal with future changes to the test script format. If a test script has a version number that .I xtmexecute does not know how to play back, .I xtmexecute will terminate with a non-zero exit status and leave an error file. .PP If a request for verification of image data from the display is in a test script, the corresponding portion of the display is read, and the information stored in the test script is used to decide if the image data has changed. .PP If the image data has not changed, .I xtmexecute will continue to play back the test script. .sp .PP If the image data has changed and checksum mode is off, .I xtmexecute will terminate with a non-zero exit status and leave an error file, a file containing the expected image data and a file containing the actual image data. .PP If the image data has changed and checksum mode is on, .I xtmexecute will terminate with a non-zero exit status and leave only an error file, since it does not have enough information in the test script to leave the expected and actual image data files. .SS Files Created by Xtmexecute .PP Messages about the progress of .I xtmexecute in playing back test scripts are recorded in log files. There is one log file for each test script. The log file's name is created by replacing the ".scr" at the end of the name of the test script with ".log". .PP If .I xtmexecute terminates normally, no error file will be created and .I xtmexecute will have an exit status of zero. .PP If .I xtmexecute terminates with an error .I xtmexecute will have a non-zero exit status and an (empty) error file will be created. The error file is created to allow easy programmatic identification of which test scripts failed when playing back more than one test script at a time. The error file's name is created by replacing the ".scr" at the end of the name of the test script with ".err". .PP If an image data verification fails and checksum mode is off, the expected and actual image data will be placed in .I xwd(1) format in expected and actual data files. The expected and actual data file names are created by replacing the ".scr" at the end of the name of the test script with ".e\fBnn\fR" and ".a\fBnn\fR", respectively. The .B nn in the expected and actual data file names will be replaced by a number corresponding to the image data verification request in the test script. The number will be 01 for the first request in the test script, 02 for the second request, and so forth up to 99 (the maximum number of requests in one test script). .PP When .I xtmexecute is playing back a test script in update mode (using the .B -u option), it creates a new test script. The new test script's name is created by replacing the ".scr" at the end of the name of the test script with ".new". If there is no error during the update of the test script, the new test script's name is changed to the original name, and the old test script is removed. If an error occurs during the update, the new test script is not renamed. .sp .SS .Xdefaults Variable Usage .I Xtmexecute recognizes the following .I .Xdefaults variables (shown with their default values): .PP .RS xtmexecute.ActionTiming: +0 .RE .RS xtmexecute.MatchRetries: .RE .RS xtmexecute.RetryInterval: .RE .RS xtmexecute.MatchBufferSize: 32760 .RE .RS xtmexecute.ReadFromRoot: no .RE .RS xtmexecute.CompareColorMap: yes .RE .PP The .I ActionTiming variable modifies the time delay for playing back each action in the test scripts. The range of time delays possible using this option is 0 to 65535 milliseconds (approximately one minute). .PP The type of time delay modification depends on the arithmetic operator preceeding the number: .TP .B + Add the (32-bit integer) number (in milliseconds) to each time delay in the test scripts. .TP .B - Subtract the (32-bit integer) number (in milliseconds) from each time delay in the test scripts. .TP .B * Multiply the (floating point) number times each time delay in the test scripts. .TP .B / Divide the (floating point) number into each time delay in the test scripts. .PP If no arithmetic operator preceeds the number, then the (32-bit integer) number will be used as the minimum time delay (in milliseconds) for each time delay in the test scripts. .PP The .I MatchRetries variable controls the number of times a failing image data comparison will be retried when the test script is played back. It has a range of 0 to 32767 retries. If the variable is not in the .I .Xdefaults file the test script will be retried the number of times that is stored in the test script. .PP The .I RetryInterval variable controls the interval in milliseconds between each retry when the test script is played back. It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). If the variable is not in the .I .Xdefaults file the delay between retries will be the amount of time that is stored in the test script. .sp .PP The .I MatchBufferSize variable controls the size in bytes of the buffer that is used to hold the data read from the display. It does not limit the amount of data that can be read from the display, but only determines how much of the data can be read at one time. .PP The value of this variable must be divisible by 8 and at least large enough to hold one line of pixels the width of the X server's display. Larger than default values of this variable may increase the performance of display reads on machines with large amounts of memory. It has a range of 0 to one-half the maximum value an unsigned integer can hold. .PP The .I ReadFromRoot variable controls whether or not to read all of the information for image data verifications in a test script from the root window instead of from the window that would normally be used. .PP If a test script was recorded by .I xtmrecord(1) with .I ReadFromRoot set to "\fByes\fR", make sure that it is set to "\fByes\fR" for .I xtmexecute as well. .PP The .I CompareColorMap variable controls whether to compare the color map or not as part of image data verification. During image data verification .I xtmexecute compares all of the colors in the color map with color map information stored in the test script. If this variable is set to "\fByes\fR", any differences are considered an error. If it is set to "\fBno\fR", any differences cause a warning instead of an error. .PP Setting this variable to "\fByes\fR" may be considered too strict. For example, a test script may not even use a given color, but all image data verifications in the test script may fail because the unused color map entry changed between the time that the verification information was stored in the test script and the time that the test script was executed. .PP If this variable is set to "\fBno\fR" and the color map entry numbers (sometimes called "pixel" numbers) stored in the test script and read from the display are the same, then a test script will not fail even if the colors associated with the color map entry numbers have changed. .SH SEE ALSO xtmrecord(1), xtmconvert(1), xwd(1). .SH COPYRIGHT .PP Copyright 1986, 1987, 1988, 1989 by Hewlett-Packard Corporation .sp .PP Copyright 1986, 1987, 1988, 1989 by the Massachusetts Institute of Technology .PP Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. .PP Hewlett-Packard and M.I.T. make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. .PP This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California. .TH XTMRECORD 1 .ad b .SH NAME xtmrecord \- interactive test script recorder .SH SYNOPSIS .B xtmrecord \fIfile\fB.scr\fR .br .SH DESCRIPTION .I Xtmrecord records a copy of the user's actions with the keyboard and mouse (called a test script) in \fIfile.scr\fR. This test script will contain a record of which keys and mouse buttons were pressed and released, where the mouse was moved to, and how long it took for the user to do it. .I Xtmexecute(1) can then be invoked to play back what was recorded in the test script. .PP While recording a test script the user may request that information about image data on the screen be recorded in the test script. When the test script is played back this recorded information is used to verify that image data currently on the screen is the same as the image data that was on the screen when the test script was recorded. .PP This allows an interactive test to be recorded and replayed, and the results of the test to be automatically verified. This also allows the construction of automated "demos" with no need for human intervention. .SS File Name Syntax The file name given to .I xtmrecord must end in ".scr". Thus: .PP .RS xtmrecord file.scr .RE .PP records an interactive test in .I file.scr. If an incorrect file name or no file name is given, .I xtmrecord will display the correct invocation syntax. .SS Running Xtmrecord .I Xtmrecord may be run in an X terminal emulator window or on a terminal. If you run .I xtmrecord on a terminal, make sure that the .SM .B DISPLAY environment variable is set to the name of the desired X server. .PP .I Xtmrecord requires that the X server support the .I Input Synthesis extension. This extension supplies the additional capabilities needed to record a test script. .PP .I Xtmrecord will communicate with the X server to start recording the user's actions as soon as it is invoked. The initial position of the mouse will be recorded, and the mouse will be moved to that position when the recording is replayed. .PP The user's actions are recorded until the user wishes to record some part of the display or terminate the recording. At that point, .I xtmrecord is placed in command mode by pressing the "command" key on the keyboard of the X server. .PP The "command" key will vary from X server to X server (on most Hewlett Packard X servers the "command" key is the left-most blank key). The "command" key may be specified by the .I CommandKey .I .Xdefaults variable. .PP While in command mode keyboard and mouse input are not passed on to the clients that would otherwise see them but instead are only passed on to .I xtmrecord. Seven commands are available in command mode, each invoked by pressing a single key: .TP .B c Cause the checksum mode to be toggled. The checksum mode is off at the start of the recording. For more information mode see the .B Checksum Mode section. This key leaves .I xtmrecord in command mode. .TP .B m Cause information about the contents of the window that is a child of the root window and contains the mouse to be recorded in .I file.scr for later use. If the window you are interested in is not a child of the root window (for example, if you are running a reparenting window manager) then you may want to use the \fBp\fR (partial window) command instead. This key leaves .I xtmrecord in command mode. .TP .B p Cause information about the contents of a user-specified partial window to be recorded in .I file.scr for later use. This key leaves .I xtmrecord in partial window specification mode. For more information see the .B Specifying a Partial Window section. .TP .B s Cause information about the contents of the entire screen to be recorded in .I file.scr for later use. This key leaves .I xtmrecord in command mode. .TP .B t Cause information about the contents of the top window (as defined by the X server) that is a child of the root window to be recorded in .I file.scr for later use. This key leaves .I xtmrecord in command mode. .TP .B r Cause .I xtmrecord to leave command mode and resume recording keyboard and mouse input. .TP .B q Cause the recording (and \fIxtmrecord\fR) to be terminated. .sp .PP The keys associated with the commands may be changed by using the appropriate .I .Xdefaults variables. For a list of acceptable keys see .B X Server Key Names in the .I xtmconvert(1) documentation. .PP If the "command" key is pressed while in command mode, the "command" key is sent on to the the client, and .I xtmrecord will leave command mode and resume recording keyboard and mouse input. This is useful if you don't have an unused key on your keyboard. Whatever key is selected as the "command" key can be used as an ordinary key by pressing it twice. .PP If no error occurs during recording, .I xtmrecord will terminate with an exit status of zero. If an error occurs during recording, .I xtmrecord will terminate with a non-zero exit status. .PP If the user wishes to see what was recorded without replaying the test script, the test script may be converted to human-readable form by .I xtmconvert(1). .SS Checksum Mode The method of image data verification depends on the checksum mode. If the checksum mode is off, the image data is stored in the test script. If the checksum mode is on, a checksum is computed from the image data and stored in the test script instead of the image data. .PP Test scripts that use checksums for image verification take up less space, but lose the ability to reproduce the expected and actual images. You know only that something has changed, but not exactly what. .SS Verification of Obscured Windows The \fBm\fR (mouse), \fBs\fR (screen), and \fBt\fR (top) commands may cause requests to read image data from a window that is partially or completely covered by other windows. Also, a useful tactic to verify something of the area around a window (such as title bars put on the window by a window manager) is to put the area of interest inside of a larger window and attempt to verify the image data in the larger window. .PP The X protocol does not guarantee correct results if you read image data from a window that is partially or completely covered by other windows, but it often works anyway. If reading from the obscured window doesn't work, reading the desired information from the root window instead sometimes works. If neither way works, then you will have to think of some other way to verify what you are interested in, perhaps using the \fBp\fR (partial window) command. .PP The .I ReadFromRoot .I .Xdefaults variable gives you the option of reading all of the information for image data verifications in a test script from the root window instead of the window that would normally be used. If you set .I ReadFromRoot to "\fByes\fR" to read image data information from the root window for .I xtmrecord, make sure to also set it to "\fByes\fR" for .I xtmexecute(1). .SS Specifying a Partial Window After the user has pressed the \fBp\fR (partial window) key, .I xtmrecord replaces the cursor with a rectangle outlining the current size and location of the partial window area on the display, and waits for the user to position the corners of the rectangle. The rectangle outlines the partial window area but is not part of the partial window area. .PP The user may then move the upper-left corner of the rectangle to near the desired position with the mouse and "fine-tune" the position with the up, down, left, and right arrow keys on the keyboard. Once the user is satisfied with the upper-left corner position, the user may press the .B d (corner "drop") key to place that corner of the rectangle. This process continues, alternating corners of the rectangle with the .B d key, until the user is satisfied with the position of the rectangle. .PP Once the user is satisfied with the position of the rectangle, the user may press the .B y key to accept the current position of the rectangle as the desired size and location of the partial window area to be recorded for later verification. .I Xtmrecord then returns to command mode unless the specified partial window area is in error. A partial window area must be contained entirely in one window. The partial window area may not be partially or completely covered by another window. If the specified partial window area does not meet these requirements when the user presses the .B y key, an error message is generated and the user is left in partial window specifying mode to permit the user to move the rectangle to fix the problem. .PP At any time the user may press the .B n key to cancel the partial window specification process and return to command mode. .PP The keys associated with specifying a partial window may be changed by using the appropriate .I .Xdefaults variables. Any key not understood by .I xtmrecord is ignored in command or partial window specifying mode. .sp .sp .SS .Xdefaults Variable Usage .I Xtmrecord recognizes the following .I .Xdefaults variables (shown with their default values): .PP .RS xtmrecord.CommandKey: KP_F1 .RE .RS xtmrecord.ResumeKey: r .RE .RS xtmrecord.QuitKey: q .RE .RS xtmrecord.ChecksumModeKey: c .RE .RS xtmrecord.MatchMouseKey: m .RE .RS xtmrecord.MatchScreenKey: s .RE .RS xtmrecord.MatchTopKey: t .RE .RS xtmrecord.MatchPartialKey: p .RE .RS xtmrecord.PlaceCornerKey: d .RE .RS xtmrecord.AcceptPartialKey: y .RE .RS xtmrecord.RejectPartialKey: n .RE .RS xtmrecord.UpKey: Up .RE .RS xtmrecord.DownKey: Down .RE .RS xtmrecord.LeftKey: Left .RE .RS xtmrecord.RightKey: Right .RE .RS xtmrecord.MatchRetries: 3 .RE .RS xtmrecord.RetryInterval: 5000 .RE .RS xtmrecord.MatchBufferSize: 32760 .RE .RS xtmrecord.ReadFromRoot: no .RE .PP The .I CommandKey variable specifies the name of the key on the X server that is the "command" key. The default value is the name for the first function key on the numeric keypad, which is the left-most blank key on most Hewlett Packard X servers. Some other X servers may not have this key, in which case some other key was chosen. The name given here must match the key chosen by the X server you are going to record from. .PP The .I ResumeKey variable specifies the name of the key on the X server that causes .I xtmrecord to leave command mode and resume recording keyboard and mouse input. .PP The .I QuitKey variable specifies the name of the key on the X server that causes the recording (and \fIxtmrecord\fR) to be terminated. .PP The .I ChecksumModeKey variable specifies the name of the key on the X server that causes the checksum mode to be toggled. .PP The .I MatchMouseKey variable specifies the name of the key on the X server that causes information about the contents of the window containing the mouse to be recorded for later comparison. .sp .sp .PP The .I MatchScreenKey variable specifies the name of the key on the X server that causes information about the contents of the entire screen to be recorded for later comparison. .PP The .I MatchTopKey variable specifies the name of the key on the X server that causes information about the contents of the top window to be recorded for later comparison. .PP The .I MatchPartialKey variable specifies the name of the key on the X server that causes information about the contents of a partial window specified by the user to be recorded for later comparison. .PP The .I PlaceCornerKey variable specifies the name of the key on the X server that causes a corner of the rectangle specifying a partial window to be placed. .PP The .I AcceptPartialKey variable specifies the name of the key on the X server that causes a partial window specification to be accepted. .PP The .I RejectPartialKey variable specifies the name of the key on the X server that causes a partial window specification to be cancelled. .PP The .I UpKey variable specifies the name of the key on the X server that causes the position of the pointer to move one pixel up during specification of a partial window. .PP The .I DownKey variable specifies the name of the key on the X server that causes the position of the pointer to move one pixel down during specification of a partial window. .PP The .I LeftKey variable specifies the name of the key on the X server that causes the position of the pointer to move one pixel to the left during specification of a partial window. .PP The .I RightKey variable specifies the name of the key on the X server that causes the position of the pointer to move one pixel to the right during specification of a partial window. .PP The .I MatchRetries variable controls the number of times a failing image data verification will be retried when the test script is executed using .I xtmexecute(1). .PP The .I RetryInterval variable controls the interval in milliseconds between each retry when the test script is executed using .I xtmexecute(1). It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days). .sp .PP The .I MatchBufferSize variable controls the size in bytes of the buffer that is used to hold the image data read from the display. It does not limit the amount of image data that can be read from the display, but only determines how much of the image data can be read at one time. .PP The value of this variable must be divisible by 8 and at least large enough to hold one line of pixels the width of the X server's display. Larger than default values of this variable may increase the performance of display reads on machines with large amounts of memory. It has a range of 0 to one-half the maximum value an unsigned integer can hold. .PP The .I ReadFromRoot variable controls whether or not to read all of the information for image data verifications in a test script from the root window instead of from the window that would normally be used. .PP If you set .I ReadFromRoot to "\fByes\fR", make sure to also set it to "\fByes\fR" for .I xtmexecute(1). .SH SEE ALSO xtmexecute(1), xtmconvert(1). .SH COPYRIGHT .PP Copyright 1986, 1987, 1988, 1989 by Hewlett-Packard Corporation .PP Copyright 1986, 1987, 1988, 1989 by the Massachusetts Institute of Technology .PP Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. .PP Hewlett-Packard and M.I.T. make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. .PP This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.