INTRODUCTION
============

xperform allows users to create scripts which mimic mouse movements.  
Coupled with a built in timing tool, xperform was designed to take
automated performance tests vs. the 5.3 desktop.  By changing the
script slightly, this can be used with any version of the desktop.


SETUP AND INSTALLATION
======================

i.    Log in as the user you wish to do performance testing as.  In
      general, you might want to create a user specifically for this
      purpose.

ii.   Execute

          /usr/local/qatools/xperform/xperform -setup

      from the performance testers $HOME directory.

iii.  Edit $HOME/script to match your system configuration
      (see below for details on the script file).  Most likely what this
      involve is substituting every occurance of the word guest with
      whatever account you decide to use.

iv.   /usr/local/qatools/xperform/xperform -start


NOTES
=====

o You might consider puttin /usr/local/qatools/xperform in the performance
  tester's path
o If you want to halt the script mid-stride, use xperform -halt.  To restart
  it, use xperform -start.
o To completely flush it from the system use xperform -unsetup


FILE AND USAGE
==============

README
------

This file contains an installation guide, usage information plus 
release notes


xperform
--------

usage:
         xperform [-options ...] < x y [delay] | filename >

where options include:
    -display <displayname>      Xserver to contact
    -config <filename>          config file (def=xperform.cfg)
    -output <filename>          log file    (def=log)
    -setup
    -unsetup
    -halt
    -start

examples:

    xperform script        # Use 'script' as a test script
    xperform 100 200       # Click the mouse at 100, 200
    xperform 100 200 15    # Click the mouse at 100, 200 with a 15 ns
                           # delay

    note: the default delay is 50


echo_autologin
--------------

Creates an empty length /etc/autologin.on file.  Make sure this file
is a root set uid process.  To do this su to root and change ownership
of this file to root.  After that, chmod 4755 the file to make it a
set uid application. 


unlink_autologin
----------------

Deletes the file /etc/autologin.on.  Make sure this file is a root set
uid process.  See echo_autologin for instructions.


script
------

The scripting language understands the following commands.  Indented
below the commands are the arguments taken.  Each command must be on a
single line.


Commands:

    #             standard comment

    $             same as #, but gets outputed to the logfile

    click         Click the mouse at a specified location
      window:
      icon:
      x:
      y:
      time:

    doubleclick   Double-click the mouse at a specified location  
      window:
      icon:
      x:
      y:
      time:

    press         Press the mouse at a specified location
      window:
      icon:
      x:
      y:
      time:

    release       Release the mouse at a specified location
      window:
      icon:
      x:
      y:
      time:

    sleep         Pause for a specified amount of time
      wait:

    kill
      window:

    .             if it's the first characted in a line marks the end of
                  a given test suite.  At the end of a test suite, the 
                  application will log out and log back in
                  automatically with the next suite.

Arguments:

   window:<name>  identifies a specific window by name.  You can use
                  xwininfo to determine the name of a window

   icon:<name>    identifies an icon by name.  Look in the file
                  .desktop-`hostname`/ozPanelLayout-1.00/Background for
                  the name of the icon.  Normally it's what ever is
                  displayed on the screen

   x:<offset>     x offset relative to upper left corner of desktop
                  unless a window or an icon has been specified in
                  which case it's relative to the upper left corner
                  of the identified window
 
   y:<offset>     y offset relative to upper left corner of desktop
                  unless a window or an icon has been specified in
                  which case it's relative to the upper left corner of
                  the identified window
 
   time:<count>   indicates that the time from the last button click
                  to the point a given window appears should be timed.
                  time:1 will measure the time to the first MapEvent,
                  time:2 will measure the time to the second MapEvent
                  so on and so forth
  
   wait:<time>    specifies a time in seconds that the application
                  should be paused.

See 'script' for an example.

