.\" Motif
.\"
.\" Copyright (c) 1987-2012, The Open Group. All rights reserved.
.\"
.\" These libraries and programs are free software; you can
.\" redistribute them and/or modify them under the terms of the GNU
.\" Lesser General Public License as published by the Free Software
.\" Foundation; either version 2 of the License, or (at your option)
.\" any later version.
.\"
.\" These libraries and programs are distributed in the hope that
.\" they will be useful, but WITHOUT ANY WARRANTY; without even the
.\" implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
.\" PURPOSE. See the GNU Lesser General Public License for more
.\" details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with these librararies and programs; if not, write
.\" to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
.\" Floor, Boston, MA 02110-1301 USA
...\" 
...\" 
...\" HISTORY
# $XConsortium: ch01.sm /main/3 1995/07/13 20:08:16 drk $
...\"  (c) Copyright 1992 OPEN SOFTWARE FOUNDATION, INC.
.H 1 "Automation Basics"
.P
This section describes what makes a test automatable. In addition, the
libraries and file-naming conventions for automated tests are described,
and instructions on building the automated test suite are provided.
.H 2 "Requirements for Automatable Tests"
.P
The following restrictions exist in the current implementation of the
automation technology. It may be possible in some cases to proceed with
limited testing even if not all these requirements are met. We welcome
your feedback on which of these restrictions poses the largest impediment,
and how you work around them.
.H 3 "XmCreate Convenience Routines"
.P
In order to automate events to any widget, that widget must be created
with the appropriate \*LXmCreate...\*O function rather than a call to \*LXtCreateWidget\*O, \*LXtCreateManagedWidget\*O, or \*LXtVaCreateManagedWidget\*O. The automation code uses
"wrappers" for the \*LXmCreate...\*O functions and stores essential information about the widgets created. You may, however, continue to use
\*LXtCreateShell\*O functions.
.H 3 "Unique XtNames"
.P
Each widget in the client under test must have a unique name, provided at
create time. Automation scripts reference widgets by this "XtName" and
the code has no algorithms for resolving duplications. This is likely
to be the most difficult restriction for large applications.
.H 3 "CommonTestInit"
.P
All test clients must start with a call to \*LCommonTestInit\*O. The function sets up signal handlers for fatal conditions, initializes the Xt toolkit, creates an application context, performs automation initialization and optional
malloc package initialization, and finally, creates and realizes an application shell called \*LShell1\*O. The presence of a single application shell by this name is also a requirement of automation. You
may pop up additional shells that have \*LShell1\*O as a parent.
.H 3 "CommonPause"
.P
Currently, all automated clients are required to have one call to \*LCommonPause()\*O.
.H 3 "Unsupported OSF/Motif Version 1.2 Functionality"
.P
Neither Drag and Drop nor \*Edragging\*O
TearOff Menus are supported by version 1.2 of
the automation libraries.
.H 3 "Private Event Loops"
.P
Clients that implement their own event loops are not automatable.
.H 3 "Resolution Independent Units"
.P
Test clients that use resolution independent units 
(for example, \*LXm1000TH_INCHES\*O) 
should only record and play back on the same screen, or on screens of the same pixel resolution. Simply, a one-inch wide button might be rendered with
97 pixels on one monitor, but require 100 pixels on another monitor. The
visual comparison code 
would report a "wrong size" error in this case.
.H 3 "The uil-Based Application"
.P
Applications which use
a uil interface are not automatable under the current
implementation.
.H 3 "XmTrackingLocate"
.P
Any calls to \*LXmTrackingLocate\*O during the execution of an automated
test will confuse event synthesis and cause an error.
.P
.H 3 "Root Window and Root Menu"
.P
There is no target in the scripting language for the root window. Consequently, one cannot, for example, post the root menu.
.H 3 "Icon Box"
The icons in the icon box can be manipulated, but the icon box itself cannot.
.H 3 "Multiple Screens"
.P
The current implementation contains no facility for record or replaying on
multiple screens of a single machine.
.H 2 "Automation Files and Directories"
.P
An automated test must be linked with the automation libraries. In addition,
supporting script and instruction files will be required, and a 
naming convention for these supporting files is described.
.H 3 "Libraries and Supporting Files"
.P
There are five libraries that support automation. 
.sp
.in +3
.VL 2.25i
.LI "\*L./tests/Auto/lib/Create\*O"
Creation routines for widgets
.LI "\*L./tests/Auto/lib/Script\*O"
The automation scripting language code
.LI "\*L./tests/Auto/lib/Visual\*O"
Visual record and compare code
.LI "\*L./tests/Auto/lib/Synth\*O"
Input synthesis library
.LI "\*L./tests/Auto/lib/Common\*O"
Convenience routines for use in tests
.LE
.in -3
.P
In addition, the following files support running the automated test suite.
.sp
.in +3
.VL 2.25i
.LI "\*L./tests/General/dirsAuto\*O"
List of automated directories
.LI "\*L./tests/General/RUN_template\*O"
Template RUN script
.LI "\*L./tests/General/bin/Genrun\*O"
Script that produces customized per-directory RUN scripts
.LE
.sp
.in -3
.P
In each automated directory exists a file \*LRUN.custom\*O, which contains specifics for running the tests in that directory under automation. For instance, this file defines the environment variable \*L$AUTOVPATH\*O, the value of which should be set to the location of the visual and output files to be used for comparison.
By issuing the command:
.sp
.nf
.in +3
\*L
make RUN
\*O
.in -3
.fi
.p
You build an executable \*LRUN\*O script which includes the directory-specific
information. You should always use the \*LRUN\*O command to run the  automated tests, to ensure the proper flags are passed to each test. In addition to the flags specified, any flags you specify to the \*LRUN\*O command itself will be passed through to each client executed within the script.
.H 2 "File Structure of an Automated Test"
.P
Each automated test is made up of the following files:
.sp
.in +3
.VL 1i
.LI "\*Lfile\*O"
test executable
.LI "\*Lfile.o\*O"
test object file
.LI "\*Lfile.c\*O"
test source
.LI "\*Lfile.h\*O"
test include [optional]
.LI "\*Lfile.dat\*O"
instructions for manual testing
.LI "\*Lfile.Dat\*O"
pre-processed instructions for manual testing
.LI "\*Lfile.scr\*O"
automation script
.LI "\*Lfile.Scr\*O"
pre-processed automation script
.LI "\*Lfile.prt\*O"
saved output (redirected \*Lstdout\*O and \*Lstderr\*O)
.LI "\*Lfile.vis\*O"
saved visual images
.LE
.sp
.in -3
.H 2 "Building Automated Tests"
.P
By default, tests are built for manual use. In order to build the tests
for use under automation, you must first:
.BL
.LI
Build the libraries under \*L$TOP/tests/Auto\*O.
.LI
Build the Makefiles in Automated test directories with a special flag.
.LI
Build the tests.
.LE
.H 3 "Building the Libraries"
.P
To build the libraries, execute the following commands, starting out in
directory \*L$TOP\*O. Note that the files \*LMotif.rules\*O and \*LMotif.tmpl\*O in \*L$TOP/config\*O contain modifications essential to automation.  If you do not use OSF's versions of these files, you will need to modify your \*Lconfig\*O files to include the necessary definitions.
.sp
.nf
\*L
.in +3
cd tests/Auto
make Makefile
make Makefiles
make
\*O
.in -3
.fi
.H 3 "Building the Makefiles"
.P
Next, build the Makefiles for the automated test directories. You may execute
the following commands in each automated directory, or write a script
that reads the file \*LdirsAuto\*O. (The \*L-DAUTOMATION\*O flag
is not propogated when Makefiles are built from the top of the \*Ltests\*O
directory.)
.P
\*L
.in +3
make IMAKE_DEFINES="-DAUTOMATION" Makefile
.in -3
\*O
.H 3 "Building the Tests"
.P
Lastly, build the tests themselves. When linked with all the automation
libraries, each test is quite large. Test executables of 2 Mb are not
uncommon. Be certain to allocate enough disk space, or write a script
that will build, run, and then clean each test directory before moving on
to the next.
.P
If the scripts for any tests contain Window Manager commands (which
start with the word \*LWindow\*O or \*LIcon\*O), 
it will be necessary to use a
OSF/Motif Window Manager (\*Lmwm\*O) built for automation. The only difference
between a default \*Lmwm\*O and one built for automation is that the latter
posts a per-window property with information about the location and size of
window manager decorations. To build \*Lmwm\*O, build the Makefile using
the same command listed above, then rebuild \*Lmwm\*O.
.P
The following restrictions about the window manager commands should be
noted:
.BL
.LI
For version 1.2, the mwm client and the server should be run on 
the same machine, or on machines using
the same byte order.
.LI
Window commands executed when a non-automated mwm is running will cause
failure messages to be printed to the output file. In addition, subsequent
visual comparisons may fail because a window was not iconified or resized
as expected.
.LE
.sp 2