XSCRIPT(1)

NAME
xscript - X Window System Script Recording and Playback

SYNOPSIS
xscript [ options ] ...

DESCRIPTION
xscript is a program which sits between an X client and an X server, monitors the events flowing from the server to the client, and records events in a script file. The script file name for recording is specified using the -r option. xscript is useful as part of a regression test system, as it can automate the playing of fixed sequences of operations into an application program based on X. xscript can play back events from a script file (specified using the -p option) to a client.

xscript can detect application-program failures during playback. To do so, it detects the failure of windows to appear as necessary for playback, and reports errors when windows do not appear within one second of when they are expected. A failure of a window to appear is symptomatic of several classes of application failures, including failure of a popup to appear and an application crash.

Upon completing a playback session which generated errors, xscript exits with nonzero status.

xscript is based on James L. Peterson's xscope program.

xscript functions as a protocol interposition process. It attaches to the X server as if it were a client, and a client attaches to xscript as if it were an X server. This allows xscript to be used for testing standard unmodified client application programs.

By adjusting the host and/or display number, the client can be made to attach to xscript instead of the X server.

    server <-----> xscript <-----> client

All bytes from the server are sent to xscript which sends them on to the client. All bytes from the client are sent to xscript which passes them on to the server. xscript is transparent to both the server and the client.

OPTIONS

-r<script-file-name>
    Requests the recording of a session and defines the script file to be written during recording.

-p<script-file-name>
    Requests the playback of a session and defines the script file to be played back. The beginning of playback is deferred until the client program attaches.

-t<time-contraction-percent>
    Specifies the percent time contraction to be used during playback. -d50 plays back a session at 50% speed, and -d200 plays it back at double speed. Changing playback speeds may foul up the client's detection of double clicks. The default time contraction is 100 percent (1:1 playback:record).

-c<double-click-time>
    Specifies the double-click-time in milliseconds. During playback when time is contracted or expanded, ButtonPress events with short delays from the previous event are handled specially so that they do not get misrecognized by the client.

-w<wait-before-playback>
    Specifies the number of seconds to wait between the time the client attaches and the first event is played back. This allows complex clients to complete drawing before playback begins. The default is five seconds.

-d<display>
    Defines the display number. The display number is added to the input and output port to give the actual ports which are used by xscript.

-h<host>
    Specifies the hostname on which xscript should look for its X server.

-h  Prints a help message.

-o<output-port>
    Determines the port that xscript will use to connect to the server (default is 0). For example, if xscript were run with the options "-hlaser -o0" it would connect to the DISPLAY named "laser:0". In the normal case it is not necessary to specify -h or -o options: xscript connects, via TCP, to the local host's zeroth display.

-i<input-port>
    Specify the port that xscript will use to take requests from clients (default is 1). For example, if xscript were running on the host named "hobie," and the option -i3 were specified, clients for recording or playback would attach to the DISPLAY named "hobie:3". Normally, it is not necessary to specify the -i option, and clients should be made to connect via TCP to "localhost:1".

-q  Quiet output mode. Gives only the names of requests, replies, errors, and events, but does not indicate contents.

-v<print-level>
    Determines the level of verbosity which xscript will provide. The print-level can be 0 (same as quiet mode), 1, 2, 3, 4. The larger numbers give more and more output. For example, a successful setup returns a string which is the name of the vendor of the X server. At level 1, the explicit field giving the length of the string is suppressed since it can be inferred from the string. At level 2 and above the length is explicitly printed.

-G<timeout>
    Determines the grab timeout. If any active grab (server, pointer, or keyboard) originating from the program under test lasts longer than this time (default 30 seconds) the xscript program terminates, releasing the grab. This feature is handy for use in debugging situations in which grabs deadlock the server.

OPERATION
When running with xscript, three processes are involved, potentially all on different machines:

X server
    The X server will run on machine (or host) "A", display "B". ("A" is a machine name; "B" is a display number).

xscript
    xscript must be told where the X server is (what machine and what display), and, in addition, the port-number on which to listen for X clients. The options for xscript are "-h<Xserver-host>" and "-d<display-number>". In this example, -hA and -dB. Typically the display-number is not given. xscript will not try to connect to the server until the client connects to xscript.

X client
    The client should connect to xscript rather than to the server. To avoid changing the code for the client, xscript listens on the same port as the server for connecting clients. If the server and xscript are on different machines, this works well. However, if the server and xscript are on the same machine, this creates a port conflict. To resolve this conflict, xscript can be given a different input or output port number, as necessary, to avoid the port that the server is listening to. The client must connect to this offset port number. The input port for xscript is set by -i<port-number>; the output port is set by -o<port-number>. The default input port is 1; the default output port is 0. These ports are offset by the X11 base (6000) and the display number. The client attaches to xscript by changing its display number by the port offset.

EXAMPLES

xscript -hbagel -r/tmp/record

The X server would be expected to be found on "bagel", display 0 (the default). xscript and the client would both be running on "cleo". The client program would think it was connecting to an X server on "cleo:1". This X server is actually xscript, which would record events and pass through requests and events to the real X server running on "bagel:0".

  server (bagel:0) <---> xscript -hbagel <---> client -d cleo:1

As it runs, xscript records input events for the client to the file /tmp/record.

xscript -p/tmp/record

The X server would be expected to be found on the local host, display 0 (the default). xscript and the client would be running on the same local host. The client would connect to "localhost:1", the xscript program, which in turn would connect to the real X server on "localhost:0".

  server (localhost:0) <---> xscript <---> client -display localhost:1

As it runs, xscript plays back pre-recorded events for the client from the file /tmp/record. If all is well, the recorded session should be reproduced.

LIMITATIONS
The X Version 11 is the only protocol recognized.

The error-detection scheme on playback is extremely limited.

The assumptions made about the similarity between the recorded and played back client sessions are easy to break.

Only one client can be recorded or played back in a session.

The builtin atoms have been wired in directly. A better solution is to pick them up from a header file.

There is no code yet to interpret typed commands from the keyboard. It would be possible for a command language at the keyboard to create artificial characters to be sent to the server or the client as if they were generated by the opposite side, or to dynamically alter requests or replies.

SEE ALSO
X(1), X11 and PEX Protocol documents

AUTHOR

James L. Peterson (MCC)

Oliver Jones

Copyright 1988, MCC

Copyright 1993, Shawsheen Software