XTMRECORD(1) — UNIX Programmer’s Manual

NAME

xtmrecord − interactive test script recorder

SYNOPSIS

xtmrecord file.scr

DESCRIPTION

Xtmrecord records a copy of the user’s actions with the keyboard and mouse (called a test script) in file.scr. 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. Xtmexecute(1) can then be invoked to play back what was recorded in the test script.

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.

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.

File Name Syntax

The file name given to xtmrecord must end in ".scr". Thus:

xtmrecord file.scr

records an interactive test in file.scr. If an incorrect file name or no file name is given, xtmrecord will display the correct invocation syntax.

Running Xtmrecord

Xtmrecord may be run in an X terminal emulator window or on a terminal. If you run xtmrecord on a terminal, make sure that the DISPLAY environment variable is set to the name of the desired X server.

Xtmrecord requires that the X server support the Input Synthesis extension. This extension supplies the additional capabilities needed to record a test script.

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.

The user’s actions are recorded until the user wishes to record some part of the display or terminate the recording. At that point, xtmrecord is placed in command mode by pressing the "command" key on the keyboard of the X server.

The "command" key will vary from X server to X server. The "command" key may be specified by the CommandKey .Xdefaults variable.

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 xtmrecord. Seven commands are available in command mode, each invoked by pressing a single key:

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 Checksum Mode section. This key leaves xtmrecord in command mode.

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 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 p (partial window) command instead. This key leaves xtmrecord in command mode.

p Cause information about the contents of a user-specified partial window to be recorded in file.scr for later use. This key leaves xtmrecord in partial window specification mode. For more information see the Specifying a Partial Window section.

s Cause information about the contents of the entire screen to be recorded in file.scr for later use. This key leaves xtmrecord in command mode.

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 file.scr for later use. This key leaves xtmrecord in command mode.

r Cause xtmrecord to leave command mode and resume recording keyboard and mouse input.

q Cause the recording (and xtmrecord) to be terminated.

The keys associated with the commands may be changed by using the appropriate .Xdefaults variables. For a list of acceptable keys see X Server Key Names in the xtmconvert(1) documentation.

If the "command" key is pressed while in command mode, the "command" key is sent on to the the client, and 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.

If no error occurs during recording, xtmrecord will terminate with an exit status of zero. If an error occurs during recording, xtmrecord will terminate with a non-zero exit status.

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 xtmconvert(1).

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.

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.

Verification of Obscured Windows

The m (mouse), s (screen), and t (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.

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 p (partial window) command.

The ReadFromRoot .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 ReadFromRoot to "yes" to read image data information from the root window for xtmrecord, make sure to also set it to "yes" for xtmexecute(1).

Specifying a Partial Window

After the user has pressed the p (partial window) key, 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.

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 d (corner "drop") key to place that corner of the rectangle. This process continues, alternating corners of the rectangle with the d key, until the user is satisfied with the position of the rectangle.

Once the user is satisfied with the position of the rectangle, the user may press the 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. 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 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.

At any time the user may press the n key to cancel the partial window specification process and return to command mode.

The keys associated with specifying a partial window may be changed by using the appropriate .Xdefaults variables. Any key not understood by xtmrecord is ignored in command or partial window specifying mode.

.Xdefaults Variable Usage

Xtmrecord recognizes the following .Xdefaults variables (shown with their default values):

xtmrecord.CommandKey:Print

xtmrecord.ResumeKey:r

xtmrecord.QuitKey:q

xtmrecord.ChecksumModeKey:c

xtmrecord.MatchMouseKey:m

xtmrecord.MatchScreenKey:s

xtmrecord.MatchTopKey:t

xtmrecord.MatchPartialKey:p

xtmrecord.PlaceCornerKey:d

xtmrecord.AcceptPartialKey: y

xtmrecord.RejectPartialKey: n

xtmrecord.UpKey:Up

xtmrecord.DownKey:Down

xtmrecord.LeftKey:Left

xtmrecord.RightKey:Right

xtmrecord.MatchRetries:3

xtmrecord.RetryInterval:5000

xtmrecord.MatchBufferSize:32760

xtmrecord.ReadFromRoot:no

The 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 Print key which is to the left of the Scroll Lock and Break keys on the Acorn Archimedes keyboard. This key must match the key which the server chooses − on many servers this will be the KP_F1 key, which is the first function key on the keypad (often marked PF1). On the Acorn A500 keyboard, where neither of these keys are available, the server uses the Menu key which must be specified in the .Xdefaults as Menu.

The ResumeKey variable specifies the name of the key on the X server that causes xtmrecord to leave command mode and resume recording keyboard and mouse input.

The QuitKey variable specifies the name of the key on the X server that causes the recording (and xtmrecord) to be terminated.

The ChecksumModeKey variable specifies the name of the key on the X server that causes the checksum mode to be toggled.

The 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.

The 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.

The 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.

The 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.

The 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.

The AcceptPartialKey variable specifies the name of the key on the X server that causes a partial window specification to be accepted.

The RejectPartialKey variable specifies the name of the key on the X server that causes a partial window specification to be cancelled.

The 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.

The 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.

The 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.

The 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.

The MatchRetries variable controls the number of times a failing image data verification will be retried when the test script is executed using xtmexecute(1).

The RetryInterval variable controls the interval in milliseconds between each retry when the test script is executed using xtmexecute(1). It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days).

The 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.

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.

The 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.

If you set ReadFromRoot to "yes", make sure to also set it to "yes" for xtmexecute(1).

COPYRIGHT

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.

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.

This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.

7th Edition

Museum

Related Articles