/* $XConsortium: README /main/4 1996/07/15 14:12:36 drk $ */
README for Automation libCommon.a
---------------------------------
The following is information about what is contained in the Automated
version of libCommon. Basically libCommon is a library which will contain
functions that are commonly called with test programs contained in the Motif
test suite. It also contains a new mechanism that will read user instructions
from a separate ascii file on test startup time instead of reading the
instructions from a header file at compile time. The difference between this
version on libCommon and the version in tests/Manual/lib/Common is that
when this library creates the applicationShell it is for Automation. It
also initializes structures for Automation and reads in special flags for
Automation.
For more information on the Automation commands, see the man pages for
Automation.
Command Line Options:
--------------------
/* Common Flags - Automation and non-Automation */
-l : Disable displaying of the MessageBox for user
instructions (Ignore CommonPause())
-w # : Specify width of MessageBox for user instructions.
Default is 60.
-u <string> : Specify a string which will be available to the
test writer as the global variable UserData.
-I <file> : Read an alternative instruction file. The default is
<test_name>.dat.
-f <font> : Use <font> as the font that will be used when your
requested font is not available. Default is fixed.
-p <font> : Specify the font to be used in the MessageBox for user
instructions. Default is fixed.
-h : Print the usage message.
/* Automation only Flags */
-a : Dump to the report file (<TestName>.prt) information on all
the specific pixel failures. When run without this flag,
the message on a CompareVisual failure will be
a one line message that the CompareVisual failed.
Only useful when running in comparison mode.
-r : Record mode. In this mode, Automation will record and save
the image currently on the screen and place it in
<TestName>.vis.
-b : Batch mode. In this mode visuals on the screen will be
compared against the visuals stored in <TestName.vis>
This is the default mode.
-m : Interactive comparison mode. In this mode, a CompareVisual
command when run in compare mode (default), will do the
following. It will bring up a another window located at
(500,500) which will be a BulletinBoardDialog with a
Drawing Area as its only child. What will be contained in
the DrawingArea after a CompareVisual will be any pixels
that failed between the comparison of the image on the screen
and the saved image in the <TestName.vis>. a black pixel
signifies failure, a white pixel signifies a pass. When
you want to dismiss this window, simply click on the
interactive window and the Automation process will continue.
-c : Ignore comparisons. In this mode all calls to CompareVisual
will be ignored.
-D <time> : Delay mode. In this mode, a Delay cycle will be executed
after each command has been executed. This valuable on slow
servers when creating and comparing visuals.
-W : Produce xwd style window dumps of the failed image. This
is triggered when a CompareVisual call fails in its comparison.
This will produce files in the current directory with the
format <TestName>_fail<n> where <n> starts at 0 and will
go up to the number of failures in the test. You then can use
xwud to display the failure images.
-S <filename>: Specify an alternative will for the script file. By default
the file Automation reads for the script commands is
<TestName>.Scr. This will allow the user to override this
convention.
-O <filename>: Specify an alternative will for the output file. By default
the file Automation dumps all STDOUT and STDERR information
is <TestName>.prt. This will allow the user to override this
convention.
-V <filename>: Specify an alternative will for the visual files. By default
the file Automation dumps visuals (in record mode) is
<TestName>.vis. This will allow the user to override this
convention.
-T : Trace mode. In this mode, all script command, with their
command number, will be echo into the .prt file. This way
the user can tell which command triggered a failure or
print statement of any kind (XtWarning, Callback information).
New Callable Functions:
----------------------
void CommonGetOptions( int argc, char **argv )
Input : argc, argv
Output : None
Purpose : This function will read the command line options and
set the appropriate flags to represent those options.
Called from CommonTestInit() always.
void CommonTestInit( int argc, char **argv )
Input : argc, argv
Output : None
Purpose : This function will do the following:
1) Will set up SIGNAL handlers "popular" signals
(SIGHUP, SIGINT, SIGQUIT, SIGKILL, and others).
The signal handler will print a message about
the termination and which signal happened. It will
then exit the test.
2) Will call CommonGetOptions() which will get all the
command line options including Automation
options.
3) Will call XtToolkitInitialize() which will
initialize the Intrinsics.
4) Will create a Application context.
4) Will make a connection to the display by calling
XtOpenDisplay(). Display variable is display.
5) Will create an ApplicationShell with
XmNallowShellResize set to true. The name of
this variable is Shell1. This shell will be
created for Automation.
6) Set the global variables screen to the Toplevel
screen and rootWindow to the TopLevel window.
7) Initialize Automation structures.
Globals : display, Shell1, rootWindow, and screen are initialized.
XtCallbackProc CommonGenericCB( Widget w, caddr_t client_data,
XmAnyCallbackStruct *call_data )
Input : Normal callback parameters
Output : None
Purpose : This is a "generic" callback routine that will simply
print to STDOUT the reason why the callback was triggered.
To be used when you want to verify that a particular
callback has been triggered.
Pixel CommonGetColor( char *ColorString )
Input : A character string corresponding to a valid color in
the rgb.txt file on your system.
Output : A color cell entry corresponding to the passed color
string. If the color does not exist, NULL will be
returned.
Purpose : This routine will convert a string representation of
a color into a Pixel value.
XmFontList CommonGetFontList( char *FontString )
Input : A character string corresponding to a font.
Output : A XmFontList corresponding to the character input.
Purpose : This routine will convert a string representation of
a font into a XmFontList. If the font you specify does
not exist on your system then default_font is used.
default_font is either read from the command line or
is defined in testlib.h (fixed).
char *CommonCsToRs( XmString cs )
Input : A XmString.
Output : A character string representation of that XmString.
Purpose : This function will convert a simple one segment compound
string into a regular character string.
void CommonPause()
Input : None
Output : None
Purpose : This function will place on the screen at (500, 0)
an MesageBox contained in a PopupShell will contains
instructions that the test writer wants the user to execute.
One call to CommonPause() corresponds to one screen of
information. The CommonPause() function will read it's
instructions from a data file (default: <test_name>.dat)
and format that information for display in the MessageBox.
The MessageBox that is created will have its help button set
insensitive. If you have tied any callbacks to this button,
you must set the help button on the MessageBox to sensitive
via SetValues().
Globals : Global InstructionBox (MessageBox) is initialized.
void CommonDumpHierarchy(Widget w, FILE *fp)
Input : A Widet, and a FILE pointer.
Output : None
Purpose : This function will "dump" all the widget names (XtName)
underneath the inputed widget. The output will be written
to the FILE specified in the argument list.
void CommonExtraResources(Arg args[], Cardinal n)
Input : An argument list and the number of arguments in that list.
Output : None
Purpose: This function will allow the user to pass resource values
to the creation of the Application Shell instead of having
to do SetValues() after the Shell has been created. It also
will allow the user to pass a different ApplicationClass to
XtOpenDisplay(). This is special cased. When you pass
"CommonAppClass" as the args[i].name then args[i].value will
be used as the ApplicationClass.
Writing Instruction Files for CommonPause() Instructions:
--------------------------------------------------
Writing instruction files for Toolkit tests are now done by creating
a file with the name <Test_Name>.dat or using the command line option
-I and specifying another file name to read as your instructions. This
file will contain special formatting characters that will be used to
determine the format of the MessageBox's message string. This file
will be read by the test program and displayed in the MessageBox when
the CommonPause() function is called. The following is a list of the
special formatting characters that can be used in the instruction file:
#) - Format the associated data as one single line of instructions.
The # character will be substituted with an instruction number
after all lines of instructions for that Panel have been
read in. The line will formatted to a specified width.
(determined either from the command line of from testlib.h)
@) - Extended format. Format data by first placing a a newline
into the data stream, followed by the associated data formatted
5 characters in from the left margin, followed by another
newline. Data will be formatted to a specified width as in
#) case. No instruction numbers will be inserted into the
data stream.
!) - No Format. Associated data will not be formatted. Use of this
format should be limited whenever possible. When it is not
possible, try to keep the width of the non formatted line to
60 characters.
C) - End of one "Panel". Specifies the end of one panel of
instructions. When this format is read, the test program
knows that it needs to display the Information Dialog with
all data between the last panel and these format characters.
Will append to the data stream a message that the user
should Continue for more testing.
E) - End of instructions. Tells the test program that it is done
with all the user instructions. Will print a Test Finished
message so that the user knows that the test is finished.
\<char> - Escape the next character. This a way of allowing all
combinations of characters in the data stream.
The format stream will be determined by reading the instruction file
until a end of panel format is found ( C) ). While the data is being
read, newlines (unless in the no format area ( !) ), tabs, and multiple
spaces (substituted with one space) will be stripped. When special
formatting characters are read ( #), !), @) ), the data stream will be
modified to insert characters to produce whatever format is asked for.
Once the data stream is filled in, a second pass is run on that
data, formatting it to a uniform length for display in the Information
Dialog.
Example of a instruction file for test foo:
------------------------------------------
foo.dat:
#) Move the pointer to the scrollbar's slider area and press Mouse
button1.\n\n #) Drag the slider to the top of the scrollbar (with key \#).
@) Note the slider will not take any input because it is insensitive
C)
#) The Scrollbar will change orientation
to\t\t\n\n
XmVERTICAL.
!)
Try the following translations:
1) BSelect Press: Select()
2) BDrag Press : Select()
E)
Will produce the following screens:
Screen 1:
1) Move the pointer to the scrollbar's slider area
and press Mouse button1.
2) Drag the slider to the top of the scrollbar (with
key #).
Note the slider will not take any input because
it is insensitive.
Press the Continue Button for more testing.
Screen 2:
1) The Scrollbar will change orientation to XmVERTICAL.
Try the following translations:
1) BSelect Press: Select()
2) BDrag Press : Select()
Test Finished -- Exit Please.