XTMEXECUTE(1) — UNIX Programmer’s Manual

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 verification of image data from the display.

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 verifying the image data, xtmexecute puts information about the current 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 verification failures. When this option is used, an image data verification failure will cause xtmexecute to leave an error file, but xtmexecute will not terminate with a non-zero exit status because of the failure.

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.

-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. Since many command interpreters use the ∗ as a pattern-matching character, you may want to use the ActionTiming .Xdefaults variable instead of this option.

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.

All test scripts contain a version number. 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 xtmexecute does not know how to play back, xtmexecute will terminate with a non-zero exit status and leave an error file.

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.

If the image data has not changed, xtmexecute will continue to play back the test script.

If the image data has changed and checksum mode is off, 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.

If the image data has changed and checksum mode is on, 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.

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 verification fails and checksum mode is off, the expected and actual image data will be placed in 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 ".enn" and ".ann", respectively. The 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).

When xtmexecute is playing back a test script in update mode (using the -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.

.Xdefaults Variable Usage

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

xtmexecute.ActionTiming: +0

xtmexecute.MatchRetries:

xtmexecute.RetryInterval:

xtmexecute.MatchBufferSize: 32760

xtmexecute.ReadFromRoot: no

xtmexecute.CompareColorMap: yes

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 the variable is not 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 the variable is not 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.

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 a test script was recorded by xtmrecord(1) with ReadFromRoot set to "yes", make sure that it is set to "yes" for xtmexecute as well.

The CompareColorMap variable controls whether to compare the color map or not as part of image data verification. During image data verification 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 "yes", any differences are considered an error. If it is set to "no", any differences cause a warning instead of an error.

Setting this variable to "yes" 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.

If this variable is set to "no" 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.

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