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 the image data within a window be recorded in the test script. When the recording is played back this recorded data is compared to the new data from the corresponding window.

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 demonstrations, with no human attention needed to manipulate almost any X clients.

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 (on the AT&T XWin GWS server the "command" key is F12.) 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. Five commands are available in command mode, each invoked by pressing a single key:

m Cause the contents of the window containing the mouse to be recorded in file.scr for later comparison.

s Cause the contents of the entire screen to be recorded in file.scr for later comparison.

t Cause the contents of the top window (as defined by the X server) to be recorded in file.scr for later comparison.

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.

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

.Xdefaults Variable Usage

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

xtmrecord.CommandKey:         KP_F1
xtmrecord.MatchMouseKey:      m
xtmrecord.MatchScreenKey:     s
xtmrecord.MatchTopKey:        t

xtmrecord.ResumeKey:          r
xtmrecord.QuitKey:            q
xtmrecord.MatchRetries:       3
xtmrecord.RetryInterval:      5000
xtmrecord.MatchBufferSize:    32760

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

The MatchMouseKey variable specifies the name of the key on the X server that causes 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 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 the contents of the top window to be recorded for later comparison.

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 MatchRetries variable controls the number of times a failing image data comparison 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 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.

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.

SEE ALSO

xtmexecute(1), xtmconvert(1).