NAME

xtmexecute - test script execution (playback) tool

SYNOPSIS

xtmexecute [-d] [-u|-c] [-t [+|-|/|*] factor] filename

DESCRIPTION

Xtmexecute plays back one or more test scripts created by xtmrecord(1) or by 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 comparisons of image data from the display with recorded image data in the test script.

File Name Syntax

If the -d option is used, then filename must be the name of a directory. Otherwise filename must end in ".scr". Thus:

xtmexecute -d testdir

will play back all of the test scripts in testdir and any directories below testdir, and

xtmexecute testscript.scr

will play back a test script testscript.scr. If no file name or an incorrect file name is given, xtmexecute will display the correct invocation syntax and terminate with a non-zero exit status but without creating an error file.

Running Xtmexecute

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

Xtmexecute requires that the X server support the Input Synthesis extension. This extension supplies the additional capabilities needed to play back a test script.

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:

-d This option allows xtmexecute to be used to run multiple test scripts. It causes xtmexecute to play back all of the test scripts in filename (which must be the name of a directory) followed by playing back any test scripts in directories below filename.

-u This option allows a test script to be updated if the expected display image data changes. When this option is used xtmexecute plays back a test script normally except that instead of comparing image data, xtmexecute puts the current display image data into the test script for later use.

-c This option causes xtmexecute to continue to play back a test script in spite of any image data comparison failures. When this option is used, an image data comparison failure will cause xtmexecute to leave an error file and files containing the expected image data and the actual image data, but xtmexecute will not terminate with a non-zero exit status because of the image data comparison failure.

This option is mostly used when playing back multiple test scripts, so that an image data comparison failure in one test script will not stop the other test scripts from being played back.

-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 ActionTiming .Xdefaults variable.

Xtmexecute will play back the actions in the test scripts in the order that the test scripts specify. 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 xtmexecute and the X server and/or delays in the X server.

If a request for a comparison of image data from the display is in a test script, the corresponding portion of the display is read, and the data is compared to that in the test script.

If the previously recorded image data matches the current image data, xtmexecute will continue to play back the test script.

If the previously recorded image data does not match the current image data, xtmexecute will terminate with a nonzero exit status and leave an error file, a file containing the expected image data, and a file containing the actual image data.

Files Created by Xtmexecute

Messages about the progress of 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".

If xtmexecute terminates normally, no error file will be created and xtmexecute will have an exit status of zero.

If xtmexecute terminates with an error 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".

If an image data comparison fails, the expected image data will be placed in xwd(1) format in an expected data file. The expected data file's name is created by replacing the ".scr" at the end of the name of the test script with ".enn".

If an image data comparison fails, the actual image data will be placed in xwd(1) format in an actual data file. The actual data file's name is created by replacing the ".scr" at the end of the name of the test script with ".ann".

The nn in the expected or actual data file names will be replaced by a number corresponding to the image data comparison 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).

.Xdefaults Variable Usage

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

xtmexecute.ActionTiming:      +0
xtmexecute.MatchRetries:
xtmexecute.RetryInterval:
xtmexecute.MatchBufferSize:   32760

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

The type of time delay modification depends on the arithmetic operator preceeding the number:

+ Add the (32-bit integer) number (in milliseconds) to each time delay in the test scripts.

- Subtract the (32-bit integer) number (in milliseconds) from each time delay in the test scripts.

* Multiply the (floating point) number times each time delay in the test scripts.

/ Divide the (floating point) number into each time delay in the test scripts.

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.

The 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 there is no MatchRetries variable in the .Xdefaults file the test script will be retried the number of times that is stored in the test script.

The 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 there is no RetryInterval variable in the .Xdefaults file the delay between retries will be the amount of time that is stored in the test script.

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

xtmrecord(1), xtmconvert(1), xwd(1).