Any required parameter that is not explicitly set will default to 0 (numeric) or "" (string),
with the exception of LOGLEVEL which defaults to -1
(meaning use the Logging Options set in the Playback Options Dialog),
wmsg which defaults to -1 (meaning not applicable) and
hrange, zsync and zinterval
which each default to their corresponding values set in the
Playback Options dialog.
Parameters marked in-out are parameters that act as
implicit variables.
| Parameter Name
| Description
| Associated Commands
|
| id
| Window Id used to identify a top-level window.
The value of this parameter persists across commands. If it is omitted from any
command that requires it, the last known value will be used for that command.
The only command for which this parameter is compulsory is the
wndInit command.
Important Note
Each window id has global scope and can only be used by one window at a time.
For example, if a script calls another script with the
_call command, the called script must
use its own unique ids for its windows. However, once a window has
been closed with a wndClose or
wndRelease command,
the identifier is freed up and can be reused by another window.
| wnd commands
ms commands
ctrl commands
kb commands
html commands
val commands
|
Window Object Parameters ^
| Parameter Name
| Description
| Associated Commands
|
wtitle
in-out
| For wndInit:
The text that appears in a main frame's title bar.
Otherwise, the 'title' of the window object that received the action,
e.g. the text that appears on a button.
| wndInit
ms commands
ctrl commands
valBitmap
valSeekItem
|
wclass
in-out
| The Windows class name of the window object that received the action.
| wndInit
ms commands
ctrl commands
valBitmap
valSeekItem
|
wpclass
in-out
| The Windows class name of wclass's parent window object.
| ms commands
ctrl commands
valBitmap
valSeekItem
|
wptitle
in-out
| The Windows title of the wpclass object.
This value is not recorded by default, and is usually not needed. It can be
added if the wclass, wtitle and wpclass parameters do not provide sufficient
information to uniquely identify a window object. The value for wptitle can be
retrieved from a TestSmith GUI Map or by using the
SpySmith tool.
| ms commands
ctrl commands
valBitmap
valSeekItem
|
wnum
in-out
| Enumeration number of window object in its hierarchy.
If a matching window object is not found at this index
it will be searched for by
wtitle, wtitle,
wpclass and wcid.
If more than one matching window object is found
a window with a matching wcid takes preference over a window
with a matching wnum.
If wnum is not explicitly used it, defaults to 0 (zero).
To force TestSmith to ignore this parameter completely
set it to a negative value, e.g. wnum=-1.
| ms commands
ctrl commands
valBitmap
valSeekItem
|
wcid
in-out
| Control ID (mainly used with Dialog controls).
If a matching window object is not found with this control id
it will be searched for by
wtitle, wtitle,
wpclass and wnum.
If more than one matching window object is found
a window with a matching wcid takes preference over a window
with a matching wnum.
| ms commands
ctrl commands
valBitmap
valSeekItem
|
| wrect
| The position and size of the main frame identified by
the id parameter.
A wrect is expressed as a string with four parts [x:y:w:h]
example -
wrect=25:20:600:450
would mean a window at screen coordinates x=25,y=20
which was 600 pixels wide and 450 pixels high.
A wrect may also be expressed as one of the following constants:
- MAXIMIZED - fills entire screen
- MINIMIZED - shows as a minimized window in the task bar
- TITLE_BAR - reduces window to just its title bar and
positions it in the top-left corner of the screen
- FIXED - window size should not change from its default
| wndMove
wndInit
|
| wx
| x-coordinate on window object.
x,y coordinates are relative to the window object, not the desktop.
When wx is used by one of the html commands
in conjunction with the hclick and halign
parameters it represents the x-offset from the html page to the IE Browser window
for the element to be clicked. Use of this parameter with
html commands is rare, however, and the
parameter is never recorded for these commands.
| ms commands
valSeekItem
Rarely (see hclick):
htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
|
| wy
| y-coordinate on window object.
x,y coordinates are relative to the window object, not the desktop.
When wy is used by one of the html commands
in conjunction with the hclick and halign
parameters it represents the y-offset from the html page to the IE Browser window
for the element to be clicked. Use of this parameter with
html commands is rare, however, and the
parameter is never recorded for these commands.
| ms commands
valSeekItem
Rarely (see hclick):
htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
|
| wxx
| x-coordinate on window object for mouse-up after a drag or scroll action.
x,y coordinates are relative to the window object, not the desktop.
| msLDrag
msLDragDrop
msRDrag
msScroll
valClipText
|
| wyy
| y-coordinate on window object for mouse-up after a drag or scroll action.
x,y coordinates are relative to the window object, not the desktop.
| msLDrag
msLDragDrop
msRDrag
msScroll
valClipText
|
| wwidth
| The wwidth and/or wheight parameters can be
added manually to a command, but should only be used when the window object
cannot be uniquely identified from the wnum and
wcid parameters.
The found wndObject must match the wwidth and/or
wheight values exactly to be accepted.
Example use:
valBitmap
id=1
wnum=27
wtitle=''
wclass=MacromediaFlashPlayerActiveX
# wcid=90273736
wpclass='Internet Explorer_Server'
wwidth=150
wheight=225
vrect=27:13:81:207
vpixelhash=266ccd9733ced0743248578f12bbc983 ;
In this example the wcid and wnum may both be different on playback
and multiple flash objects are embedded in the html page.
Inclusion of the wwidth or wheight params will automatically ignore
the wcid param (which can also safely be removed or commented out, as above).
The window will be found by matching the title, class, class and the width/height.
This assumes the width/height of the flash object is both constant and unique
to one particular flash object.
| ms commands
wndFindObj
valBitmap
valSeekItem
|
| wheight
| See details under the wwidth parameter.
| ms commands
wndFindObj
valBitmap
valSeekItem
|
| wmsg
| Parameter to override the
Mouse Messages playback setting.
If Mouse Messages = TRUE, wmsg can be set to 0 in order to force absolute positioning
for a single command.
If Mouse Messages = FALSE, wmsg can be set to 1 in order to force the sending of a mouse
message for a single command.
| ms commands
valClipText
|
Control Object Parameters ^
| Parameter Name
| Description
| Associated Commands
|
| ctext
| The text to be entered in the Edit field.
| ctrlEditSetText
|
| cedit
| A value to determine the type of edit operation.
The value is not case-sensitive. Supported values are:
- BEGIN - insert the text at the beginning of any existing text.
- END - insert the text at the end of any existing text.
- REPLACE - replace the existing text completely with the new text.
If the cedit parameter is not there or has any other value, the
ctext will be entered at the point of the cursor.
| ctrlEditSetText
|
| ccheck
| Value that sets the checkbox state: 1 = checked, 0 = unchecked.
| ctrlButtonCheck
|
| citem
| The value of the item to be set. For ComboBox controls and for single-select ListBox
controls the value should be single text string; for multi-select ListBox controls
the value can be a single string or a comma-separated list of strings.
| ctrlListSetItem
|
| cindex
| This parameter is used differently for the two commands it applies to.
When used with ctrlListSetItem it represents
the index of the item to be set. For ComboBox controls and for single-select ListBox
controls the value should be single numeric value; for multi-select ListBox controls
the value can be a single numeric value or a comma-separated list of numeric values.
When used with valListItem it forces the
vitem to be compared with only the item at the specified index.
If cindex is not used or is set to 0, vitem is compared with
all the items in the list.
NOTE: indexing of lists begins at 1.
| ctrlListSetItem
valListItem
|
| cexact
| By default the item selected using the citem parameter will be
the first item that starts with the citem value (case insensitive),
e.g. citem=AC will match with Acrobat.
If an exact (and case-sensitive) match is required set this
parameter to a non-zero value.
| ctrlListSetItem
|
| cclear
| Used with multi-select ListBox controls only. If set to a non-zero value
the previous ListBox selections will be cleared before the new selections
are applied. By default the previous values will not be cleared.
| ctrlListSetItem
|
| Parameter Name
| Description
| Associated Commands
|
| ktext
| The text to be typed into the window or text box,
or (optionally) an HTML element.
See Character Substitutions for additional information.
| kbText
htmlText
|
| kkey
| The decimal number representing the Key Code of the system key, or
a readable key name. The following key names are supported:
- Space
- PageUp
- PageDown
- End
- Home
- LeftArrow
- RightArrow
- UpArrow
- DownArrow
- Snapshot
- Insert
- Delete
- Backspace
- Help
- Enter
- Tab
- F1 - F12
The ASCII keys A - Z and 0 - 9 will be recorded as system keys if the
Ctrl and/or Alt key is depressed. The alpha characters (A - Z) are
represented by the character itself. The numeric characters (0 - 9) are also
represented by the character itself, but preceded by a 'k' character,
i.e. k0 - k9.
All readable names and character representations are case-insensitive.
| kbKey
|
| krep
| The key repeat count.
The key message is sent this number of times on playback.
| kbKey
|
| kstate
| State of the Shift, Ctrl and Alt keys (or'ed together), where
- Shift = 1
- Ctrl = 2
- Alt = 4
Example: to simulate the holding down of the Shift and Ctrl keys
together use a value of kstate=3
| kbKey
ms commands
|
| kkeybd
| Use only in conjunction with ktext.
By default, TestSmith uses the Windows clipboard as a delivery
mechanism to send text to a window object (i.e. kkeybd=0).
This method allows atomic entry of text and can support
any character in the ASCII 32-255 range. If this method fails for
some reason, set the parameter to kkeybd=1 to instruct TestSmith
to enter the text using simulated keyboard key presses.
Please note that keyboard simulation will fail on any character
that is in the 128-255 range
(e.g. Æ, ß, ñ).
| kbText
htmlText
|
| Parameter Name
| Description
| Associated Commands
|
| menuitem
| A string of ASCII characters, upper or lower case, representing the keys
used as mnemonics for selecting a menu item. The four characters
'<', '>', '{' and '}'
are not used as mnemonics but will be translated as:
-
< Left Arrow key
-
> Right Arrow key
-
{ Up Arrow key
-
} Down Arrow key
Note that only interaction with special menus such as the
Windows Start menu will
require the use of the arrow keys.
Each character in the menuitem string can be optionally separated from its neighbour
by a '/' or '~' character.
Example: to select the Help/About menu item in Notepad the parameter could be specified
as menuitem=H/A, menuitem=h~a, menuitem=Ha, etc.
| kbMenuSelect
|
| menugo
| A string of characters representing the 4 direction arrow keys,
up (U or u), down (D or d), left (L or l) and right (R or r).
Each letter represents a single key press on one of the arrows.
Example: to select the Help/About menu item in Notepad the parameter could be
specified as menugo=RRRDD or menugo=rrrdd.
The optional separator characters described above can also be used for this parameter.
| kbMenuSelect
|
| Parameter Name
| Description
| Associated Commands
|
| htitle
| The title of the HTML document.
| valHtmlTitle
|
| hframe
| The name of the frame in which the html action occurred.
For multiple embedded frames this will be a path-style name such
as right/left/top.
| html commands
valHtmlElem
valHtmlText
|
| htag
| The tag name of the element, e.g. BODY, INPUT, A, etc.
| html commands
valHtmlElem
valHtmlText
|
hidx
in-out
| DOM index of a HTML Element.
| html commands
valHtmlElem
valHtmlText
|
| hrange
| The range in which to search for an element that is not found at
the original hidx.
If this parameter is not specified the value from the
Html Element Search Range setting in the
Playback Options Dialog is used as a default.
The recommended range for this setting is 25 which means that the closest
50 elements (25 above, 25 below) are checked for a match. If a match is
not found in that range an error is generated.
If a greater or smaller range than the default is required for
a particular command the hrange parameter must be explicitly set.
If hrange is set at 0 only the element at the specified index is checked.
If hrange is set at -1 all the elements in the document are checked.
Warning: For large HTML pages (over 1000 elements) checking
all elements will consume CPU time and will slow down playback.
It is advisable to specify a range.
| html commands
valHtmlElem
valHtmlText
|
| hid
| The string specified in the ID property of the element being recorded.
NOTE: In practice this is rarely used. TestSmith encourages its use!
| html commands
|
| hparentid
| The string specified in the ID property of the parent element of the element
being interacted with (only useful if the ID property of the parent
element has been explicitly set).
Use of this parameter allows greater degree of exactness in identifying
a particular element during playback.
| html commands
|
hhref
in-out
| The URL (or other, e.g. javascript:directive) specified in the
element's 'href' property.
| htmlLink
|
hsrc
in-out
| The URL (or other, e.g. javascript:directive) specified in the
INPUT element's 'src' property when type=image.
| htmlInput
|
hname
in-out
| The string specified in the NAME property of the element being recorded.
| htmlSelect
htmlCheck
htmlInput
htmlText
|
hvalue
in-out
| The string specified in the VALUE property of the element being recorded.
For htmlText commands this will be
the value of the text just entered.
| htmlSelect
htmlCheck
htmlInput
htmlText
|
| htype
| The string specified in the TYPE property of the element being recorded.
| htmlSelect
htmlCheck
htmlInput
htmlText
|
hhtml
in-out
| By default the value for hhtml that is recorded is the opening tag,
e.g. <INPUT name=this value=that>.
For valHtmlElem this can be changed
to represent either the complete inner or complete outer html, but
will need some manual intervention, which is described here.
When you use Ctrl+RightClick or Alt+RightClick on an html element during
a recording session a popup box appears showing the element's full html
(along with some other properties such as its index in the DOM mode and the
containing frame name).
Clicking the "Validate Element" button will capture the html of the opening
tag in the valHtmlElem command;
if you prefer to capture the inner or outer html you should first
select and copy the appropriate block of html before clicking
the "Validate Element" button. Once the command has been recorded, go to
the script and replace the tag html with the html you just copied.
You'll need to remove any newline characters that were put in for formatting
purposes, and you may need to replace characters such as
# ; ' and others
with TestSmith character substitution strings.
You will also need to change the value of the
hhtmltype parameter.
Example:
Given the html
<TD align=top>Click <A href=info.html>here</A>
for information</TD>
<TD align=top>
is the default tag html that will be recorded.
Click <A href=info.html>here</A> for information
is the inner html.
<TD align=top>Click <A href=info.html>here</A>
for information</TD>
is the outer html.
| valHtmlElem
htmlClick
htmlSaveImg
|
| hhtmltype
| A constant (but case-insensitive) string that represents the type of
html to be validated, as represented by the
hhtml parameter.
The acceptable values are:
If any other value is used, or if the hhtmltype parameter is absent
the default TAG will be assumed.
| valHtmlElem
htmlSaveImg
|
hvistext
in-out
| The visible text that appears for the element. When recorded the text is truncated to
32 characters for all commands except valHtmlText.
This is not a playback restriction, however, and the string can be edited to be longer
or shorter as preferred.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
valHtmlElem
valHtmlText
|
hfailtext
in-out
| The text that will cause an immediate ERROR to be returned if it
is found (anywhere) on the page. This allows for the http request to result
in an error page, e.g. a 404 page,
and prevents the zsync parameter from performing multiple searches of
the page to try to match text that is never going to be there.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
htmlChoice
valHtmlElem
valHtmlText
htmlSaveImg
|
| hoffset
| Character offset from start of selected text string.
| valHtmlText
|
| hchecked
| Value of 1 or 0, depending on whether the radio or checkbox element
should be checked or not.
| htmlCheck
|
| hoption
| Use for single-select objects. This parameter specifies the position
in the list for the item to be selected, 1 being the first item.
NOTE: if the hevent parameter is being used this parameter
must be removed and the hoptkey parameter used instead.
| htmlChoice
|
| hoptval
| Use for single-select objects. This parameter specifies the value
representing the item to be selected.
Either the internal value or the visible text of an option
can be used for this parameter.
The playback engine will first try to match on the internal value, and if
that fails it will attempt to match on the visible text.
NOTE: if the hevent parameter is being used this parameter
must be removed and the hoptkey parameter used instead.
| htmlChoice
|
| hoptions
| Use for multiple-select objects. This parameter specifies the positions
in the list for the one or more items to be selected, 1 being the first item.
This parameter value is formatted as a comma separated list, e.g.
hoptions=1,3,5 .
NOTE: if the hevent parameter is being used this parameter
must be removed and the hoptkey parameter used instead.
| htmlChoice
|
| hoptvals
| Use for multiple-select objects. This parameter specifies the set
of values representing the items to be selected.
Either the internal value or the visible text of an option
can be used for this parameter.
The playback engine will first try to match on the internal value, and if
that fails it will attempt to match on the visible text.
This parameter value is formatted as a comma separated list, e.g.
hoptions=red,green,purple .
NOTE: if the hevent parameter is being used this parameter
must be removed and the hoptkey parameter used instead.
| htmlChoice
|
| hoptkey
| The hoptkey parameter must be used to set the value of a <SELECT>
element whenever the hevent parameter is specified for a
htmlChoice command. The value for hoptkey
should be the first character of the option to be selected. If there is more
than one option beginning with the same character, that character should
be repeated the appropriate number of times.
Examples:
Given the following list: "Ant Bee Beetle Butterfly Caterpillar" use
hoptkey=A to select Ant
hoptkey=B to select Bee
hoptkey=BB to select Beetle
hoptkey=BBB to select Butterfly
hoptkey=C to select Caterpillar
| htmlChoice
|
hclick
deprecated
|
This parameter has been deprecated.
Please use hevent instead.
The hclick parameter, when set to 1, forces any html command to use an actual mouse click
(or mouse message) instead of sending a click event through the HTML DOM model.
This parameter should only be used in cases where the HTML DOM approach fails,
for example when a Javascript modal dialog window (popup) appears during a playback.
When this happens the popup will freeze the playback until it is manually closed.
This is true even if the Javascript window was successfully recorded.
The use of the hclick=1 parameter will overcome this problem.
Another common situation where it is required is when showing a
File Dialog box using the HTML <INPUT type=file> element.
See the Mouse Messages option
and the wmsg parameter for details on how a mouse click is sent.
Warning:
If the item to be clicked is not visible on the screen or if the item can only
be made visible by scrolling it into view then the hhalign parameter,
in conjunction with the wx and wy parameters must be used
for the click to be successful. Some initial experimentation may be needed with the
wx and wy values to get accurate positioning.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
|
| hevent
| Use hevent=1 with any html command to trigger
an associated event such as 'onchange()' or 'onclick()'.
If this parameter is not included the event will not be triggered, or in
some cases (such as javascript popups) the playback will freeze.
If this parameter is being used with a
htmlChoice command the
hoptkey parameter should be used to select the
required option.
This parameter should be used instead of the hclick
parameter which is now deprecated. hevent is not dependent on the html
element being visible in the window, and needs no adjustment to
compensate for nested frames.
NOTE:
Because this parameter initiates a keybd message to trigger the event
scripts containing this parameter should not be run in the background
(i.e. while a user is working on the same machine). Additionally
the application under test cannot be minimized; it can however be set
to a minimal size on the desktop. One way of achieving this is to use
the wrect=TITLE_BAR setting to resize the window to its
title bar only, which is then positioned at the top-left of the desktop.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
htmlChoice
|
| halign
| Use this parameter to align the corresponding html element with either the
top or bottom of the IE browser window. Acceptable values (not case sensitive) are
If the page size is such that the element cannot be aligned exactly with the top or bottom
of the window, then it is repositioned as close as possible to the chosen position.
NOTE:
Use of the halign parameter together with the wx and wy
parameters is essential if the hclick parameter is set to 1 and the
element to be clicked is not visible on the html page.
| html commands
|
| url
| The full URL of the page to be requested, navigated to, or validated.
The length of the url cannot exceed 1024 characters.
| inetRequest
htmlNavigate
valHtmlUrl
|
Synchronization Parameters ^
| Parameter Name
| Description
| Associated Commands
|
| zsync
| Run the command and if the command causes an error wait a specified
length of time and then run the command again, and again...
A value of 0 for zsync means do not synchronize (i.e. check once only
and continue, despite result. This is the same as not using the zsync
parameter). Any non-zero value means do attempt to synchronize.
The value itself is used as the number of milliseconds to wait
before retrying and then immediately timing out,
(see also Time Parameters, below).
The number of times to retry before the zsync timeout is reached is
specified by either the zinterval parameter
or ztries parameter.
If neither parameter is specified the command is not retried until the
timeout is reached, as described above.
NOTE:
If zsync is unspecified for any of the commands listed in the
command group in the adjacent column the
Default Sync Timeout value will be used.
| html commands
val commands
ms commands
ctrl commands
wnd commands
|
| zinterval
| Time between rechecks, specified in milliseconds.
See also ztries.
NOTE:
If zinterval is unspecified for any of the commands listed in the
command group in the adjacent column the
Default Sync Interval value will be used.
| html commands
val commands
ms commands
ctrl commands
wndInit
|
| ztries
| Number of times to retry before ztries timeout reached.
See also zinterval.
NOTE: zinterval takes priority over ztries if both are used.
| html commands
val commands
ms commands
ctrl commands
wndInit
|
| Parameter Name
| Description
| Associated Commands
|
| vpixelhash
| One or more values representing the bitmap to be compared.
A pixel hash is an MD5 hash of all the pixels in the bitmap. There may be
more than one pixel hash match in the case of Flash objects
(see Flash Objects sometimes need color adjustment.
When multiple pixel hashes are specified they should be separated by a | (pipe) character.
One of the pixel hash(es) in the list must match exactly with the recorded pixel hash
for this command to be successful. If the command fails, the pixel hash that was found
is shown in the report. If necessary, this pixel hash can be added to the list
so the command will pass on the next run.
When creating valBitmap or
valSeekItem commands - especially on Flash
objects - it is often necessary to run the command a few times to collect all the
possible pixel hashes for that object. Empirical evidence shows that objects of
this type appear to require between 2-4 different pixel hashes in order to match
consistently.
Note: since v1.3 this parameter replaces the vchecksum and
vseekkey parameters, which are now deprecated.
| valBitmap
valSeekItem
|
| vrect
| The bitmap rectangle.
A vrect is expressed as a string with four parts [x:y:w:h]
example:
wrect=5:8:80:40
would mean a bitmap at window object coordinates x=5,y=8
which was 80 pixels wide and 40 pixels high.
| valBitmap
|
| voutline
| Show a dotted line around the bitmap being validated. This parameter is not recorded
but can be set to voutline=1 if an outline is required. This is useful
as a visual aid only and has no other purpose.
| valBitmap
|
vtext
in-out
| The selected text to be validated.
A fuzzy match can be achieved by using the
vtext~ parameter.
| valClipText
valEditText
|
| vitem
| The item in a ListBox or ComboBox control to be validated. The match must be
exact for the validation to succeed.
| valListItem
|
| vseektype
| Indicates the item type for a valSeekItem command. One of four possible
values will be recorded:
vseektype=image1 - small image item (8 x 8 pixels)
vseektype=image2 - large image item (16 x 16 pixels)
vseektype=text1 - small text item (32 x 6 pixels)
vseektype=text2 - large text item (48 x 8 pixels)
See the Seek Item documentation for more information.
| valSeekItem
|
| vsquare
| This parameter specifies the size of (one side of)
the square in which the item is to be sought. It is only used if the
vaxis parameter value contains an 's'.
Example: if vsquare=100 the item to be found
would be sought in a 100 x 100 pixel square,
with the original point being at the center of the square. If the value
of vsquare is less than 2 the default square of 64 x 64 pixels is used.
| valSeekItem
|
| vaxis
| The axis, axes or area in which to search for an item.
By default the value is vaxis=xy, meaning search along both
the x and the y axis.
Change this value to vaxis=x or vaxis=y to
seek along only a single axis.
Change this value to vaxis=s
to seek each point in the surrounding square area, defined by the value of
vsquare. If vsquare is not used
the default square of 64 x 64 pixels is used.
Any combination of x, y and s can be used, in any order.
See the Seek Item documentation for more information.
| valSeekItem
|
| vxinc
| Value to increment the x coordinate by.
When searching along the y axis and the item is not found, the search can be continued
starting at a new location determined by the original y coordinate and
a new x coordinate calculated by adding a vxinc value to the original x coordinate.
The format of the vxinc parameter can either be a single value, a comma-separated
list of values or a calculation using the multiplication operator *.
Examples:
vxinc=16 - search one more column (y-axis) starting 16 pixels to the
right of the original starting point.
vxinc=-16 - search one more column (y-axis) starting 16 pixels to the
left of the original starting point.
vxinc=10,20,30 - search 3 more columns (y-axis) starting 10, then 20,
then 30 pixels to the right of the original starting point.
vxinc=12*8 - search 8 more columns (y-axis) starting 12, then 24,
etc. pixels to the right of the original starting point.
See the Seek Item documentation for more information.
| valSeekItem
|
| vyinc
| Value to increment the y coordinate by.
When searching along the x axis and the item is not found, the search can be continued
starting at a new location determined by the original x coordinate and
a new y coordinate calculated by adding a vyinc value to the original y coordinate.
The format of the vyinc parameter can either be a single value, a comma-separated
list of values or a calculation using the multiplication operator *.
Examples:
vyinc=16 - search one more row (x-axis) starting 16 pixels
below the original starting point.
vyinc=-16 - search one more row (x-axis) starting 16 pixels
above the original starting point.
vyinc=10,20,30 - search 3 more rows (x-axis) starting 10, then 20,
then 30 pixels below the original starting point.
vyinc=12*8 - search 8 more rows (x-axis) starting 12, then 24,
etc. pixels below the original starting point.
See the Seek Item documentation for more information.
| valSeekItem
|
| vsilent
| By default the mouse pointer is moved along the plane(s) on which the item is being sought.
Set this parameter with the value vsilent=1 to override this behavior.
See the Seek Item documentation for more information.
| valSeekItem
|
| vmenufixed
| If the item being sought is a menu item on the main menu bar of the application,
and this menu bar is of the older 'fixed' type of menu bar then this parameter should
be added with the value vmenufixed=1.
See the Seek Item documentation for more information.
| valSeekItem
|
| voutside
| Set the parameter voutside=1 if the item being sought overlaps
the main frame (often true with menu items, or toolbar extensions).
| valSeekItem
|
vseekkey
deprecated
|
This parameter has been deprecated in favour of
vpixelhash.
A unique key for the item to be sought. It is this key that is searched
for if the item is not found where it was when the recording was made.
| valSeekItem
|
vchecksum
deprecated
|
This parameter has been deprecated in favour of
vpixelhash.
One or more checksums representing the bitmap to be compared.
A checksum is simply the sum of all the pixels in the bitmap. There may be
more than one checksum match in the case of Flash objects
(see Flash Objects sometimes need color adjustment.
When multiple checksums are specified they should be separated by a | (pipe) character.
The checksum(s) must match exactly the checksum made on playback, but
by using the vvariation parameter a match can still
be made with a bitmap that has had one or more pixels altered.
| valBitmap
|
vvariation
deprecated
|
This parameter has been deprecated along with
checksum and
vseekkey.
The allowed variation (+-) of the vchecksum value.
The higher the number, the more approximate the bitmap match will be.
This parameter is useful if you anticipate that certain pixels
will have changed, or the overall color is slightly lighter
or darker, between recording and playback.
This parameter can also be used with
valSeekItem commands. However, it is
recommended that it is not used, except in special cases, e.g. in the case
of Flash objects, when the color range of the object can vary slightly from
one playback to the next, and the normal valSeekItem command is unable to
find a match.
| valBitmap
valSeekItem
|
The fuzzy-matching equivalents of
wtitle,
wclass,
wpclass,
vtext,
hname,
hvalue,
href,
hsrc,
hvistext,
htitle,
hfailtext,
hhtml,
url,
iheaders,
icontent.
Fuzzy parameters are identical to their non-fuzzy equivalents with the addition
of the '~' character at the end of the parameter name, e.g.
wtitle~ is the fuzzy equivalent of wtitle
NOTE: The '~' character cannot be used at the end of any
other parameter name than those listed above. If it is used, the entire parameter
will not be recognized and will therefore be ignored.
Logical Operators
Fuzzy matching requires the use of one of three special operator symbols as the
first character in the string to be matched:
& AND
| OR
^ XOR
Example AND: hvistext~=&apple,John,Smith
Example OR: hvistext~=|apple,John,Smith
Example XOR: hvistext~=^apple,John,Smith
The & (AND) symbol directs TestSmith to match a string containing all of the
specified search terms.
Examples: "John Smith eats apples" will pass but "John Smith eats pears" will fail.
The | (OR) symbol directs TestSmith to match a string containing any one
(or more than one) of the search terms.
Examples: "John Smith", and "Jane Smith" and "apples" and "TestSmith" will pass
but "Jane eats pears" will fail.
The ^ (XOR) symbol directs TestSmith to match a string containing one
and only one of the search terms.
Examples: "Jane Smith likes pears" will match but "Jane Smith likes apples" will
fail because two of the terms match.
NOTE: The search terms are not treated as whole and complete words, thus "Johnapple"
in the text would match on two of the terms, "John" and "apple".
To have terms treated as whole words, surround each term with spaces, either as
quoted strings or using "%--" (or "%20").
The above example would then become:
hvistext~=&%--apple%--,%--John%--,%--Smith%-- or
hvistext~=&' apple ',' John ',' Smith '
and would fail on "Johnapple".
Ignore Case:
To ignore case in the comparison, add the string `i to the end of
the set of search terms.
The above OR example would become: hvistext~=|apple,John,Smith`i.
This would match on "APPLE", "johnsmith", jOhNs, "JOHN EATS PEARS", etc...
| | Parameter Name
| Description
| Associated Commands
|
wtitle~
in-out
| Fuzzy version of wtitle.
See details.
NOTE: for the wndInit command
this parameter will have no effect if applied to the
Desktop Window or the Desktop Task bar Window, as their titles
are fixed and final.
| wndInit
ms commands
ctrl commands
|
wclass~
in-out
| Fuzzy version of wclass.
See details.
NOTE: for the wndInit command
this parameter will have no effect if applied to the
Desktop Window or the Desktop Task bar Window, as their class names
are fixed and final.
| wndInit
ms commands
ctrl commands
|
wpclass~
in-out
| Fuzzy version of wpclass.
See details.
| wndInit
ms commands
ctrl commands
|
wptitle~
in-out
| Fuzzy version of wptitle.
See details.
| wndInit
ms commands
ctrl commands
|
vtext~
in-out
| Fuzzy version of vtext.
See details.
| valClipText
valEditText
|
hname~
in-out
| Fuzzy version of hname.
See details.
| htmlSelect
htmlCheck
htmlInput
htmlText
|
hvalue~
in-out
| Fuzzy version of hvalue.
See details.
| htmlSelect
htmlCheck
htmlInput
htmlText
|
hhref~
in-out
| Fuzzy version of hhref.
See details.
| htmlLink
|
hsrc~
in-out
| Fuzzy version of hsrc.
See details.
| htmlInput
|
hvistext~
in-out
| Fuzzy version of hvistext.
See details.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
valHtmlElem
valHtmlText
|
htitle~
in-out
| Fuzzy version of htitle.
See details.
| valHtmlTitle
|
hfailtext~
in-out
| Fuzzy version of hfailtext.
See details.
| htmlSelect
htmlCheck
htmlInput
htmlLink
htmlClick
valHtmlElem
valHtmlText
|
hhtml~
in-out
| Fuzzy version of hhtml.
See details.
| valHtmlElem
|
url~
in-out
| Fuzzy version of url.
See details.
| valHtmlUrl
|
iheaders~
in-out
| Fuzzy version of iheaders.
See details.
| inetRequest
|
icontent~
in-out
| Fuzzy version of icontent.
See details.
| inetRequest
|
| Parameter Name
| Description
| Associated Commands
|
| file
| The full path name of the file to be sought, read or written to
(for the fdExist command this is the name of a directory).
Spaces and other reserved characters in a file name must be represented by
standard TestSmith replacement characters.
Example use: fExist file=C:\Program%--Files\myfile.txt
| fRead
fWrite
fAppend
fCopy
fMove
fCompare
fExist
fdExist
htmlSaveImg
|
| file2
| The full path name of the second file to be read or written to.
Details as above.
| fCopy
fMove
fCompare
|
| ftext
| The text to be written to a file.
Can be literal text or a TestSmith variable.
Example use: fWrite file=d:\myfile.txt ftext={myVariable} ;
| fWrite
fAppend
|
| fmatch
| Set to a non-zero value to force an ERR to be returned when the two files
being compared in a fCompare command
do not match.
If this parameter is not set (or is set to 0) an OK result is always returned.
NOTE: The INFO line generated by the fCompare
command will always indicate whether the two files match or not.
| fCompare
|
| Parameter Name
| Description
| Associated Commands
|
| rkey
| The full path name of the registry key to be written to.
Example: HKEY_CURRENT_USER\Software\Some%--Vendor\Some%--Name\
| regRead
regWrite
|
| rvalue
| The specific value of the registry key to have its data read or written to.
| regRead
regWrite
|
| rdata
| The data to be written to the registry key value. Can be either a text value
or an integer value, depending on the required data type.
| regWrite
|
| rtype
| The type of the data to be read or written. The value should be one of
the two (case-insensitive) constants:
rtype=int - an integer
rtype=str - a text string
If this parameter is not specified the type is considered to be str
by default.
| regRead
regWrite
|
| Parameter Name
| Description
| Associated Commands
|
iheaders
in-out
| Specify a text string to match with the headers returned by the request.
This parameter will perform an exact match; use the
iheaders~ parameter to find a substring or set
of substrings in the response headers.
| inetRequest
|
icontent
in-out
| Specify a text string to match with the content returned by the request.
This parameter will perform an exact match; use the
icontent~ parameter to find a substring or set
of substrings in the response content.
| inetRequest
|
| isize
| Specify a size in bytes (the content length) to match with the size of
the content returned by the request.
| inetRequest
|
| imodtime
| Specify a complete or partial date/time to match with the last modified time of
the content returned by the request. This parameter is formatted as a
text string using the following rules and guidelines:
- The string order must be year, month, day, hour, minute, second -
YYYY:MM:DD:hh:mm:ss.
- Each element is represented by a numeric value.
- A separator character must be used between each element.
Supported separator characters are
/ : | -
- The year element must contain the full 4 digits, e.g. 2004.
- A single leading zero may be used with other elements if the
value for that element is less than 10
(use of the leading zero is optional).
- A date can be partial, but must always start with the year and
must always retain the correct ordering, thus (for example)
YYYY and YYYY/MM/DD are acceptable but
hh:mm:ss and YYYY:hh:mm:ss are not.
Variable timestamps can be used in place of hard coded strings.
See TestSmith Timestamps for more information.
| inetRequest
|
To specify any time parameter in units other than milliseconds use the format:
Sn for number of seconds
Mn for number of minutes
Hn for number of hours
These cannot be mixed, so if you wanted to specify, e.g. two and a half hours
you would need to use sleep=M150.
| | Parameter Name
| Description
| Associated Commands
|
| mtime
| Number of milliseconds the mouse button is held down.
| ms commands
|
| sleep
| Number of milliseconds to pause before next command.
| all commands
|
| zsync
| see Synchronization Parameters
| zinterval
| see Synchronization Parameters
| |
String Manipulation Parameters ^
Three parameters to support text string manipulation when assigning a value
to a variable using a setVar command.
One or more of these parameters can be used together. The strtrim parameter will
always be applied after the string has been chopped according
to stroffset and/or strlength. To apply a trim action beforehand, a separate
setVar command will need to be used,
which contains only the value to be set and the strtrim parameter.
Example:
setVar strVar1=' Hello, I am a tester of software. ' ;
setVar strVar2={strVar1} stroffset=8 strlength=15 strtrim=LR ;
will result in strVar2 having the value: "I am a tester".
The string will go through the following transitions:
stroffset=8 creates: " I am a tester of software. "
strlength=15 creates: " I am a tester "
strtrim=LR creates: "I am a tester"
These parameters also work for assigning an int variable.
Example:
setVar intVar1=12345 ;
setVar intVar2={intVar1} stroffset=1 strlength=2 ;
will result in intVar2 having the value 23.
Caution:
If multiple variables are specified in a setVar command
these parameters will be applied to each of them. It is advisable to use only a
single variable with each setVar command.
| | Parameter Name
| Description
| Associated Commands
|
| stroffset
| Syntax: stroffset=n where n is a numeric value.
The value of the variable will be copied from that index in the string,
thus the command:
setVar var1='john smith' stroffset=5;
will result in the variable var1 containing the string "smith".
Another way to think of this is chopping off the first n characters of
the string.
See overview.
| setVar
|
| strlength
| Syntax: strlength=n where n is a numeric value.
The value of the variable will be a string n characters long
counted from stroffset, or from 0 if no offset is defined.
See overview.
| setVar
|
| strtrim
| Syntax: strtrim=L|R|LR
Trim whitespace (spaces and tabs) from either the Left, the Right
or both the Left and the Right of the variable value.
See overview.
| setVar
|
| Parameter Name
| Description
| Associated Commands
|
| errlevel
| A user defined value that must be greater than zero.
This is the value that will be used as the error code for the command it is
specified for. Using this parameter the script creator can categorize errors
according to type or severity. The scripts return code will be the highest (worst)
error code produced in the run, unless the ERRJOIN
directive is used, in which case the return code will be a combined one
(using either AND or OR) of all the errors that occurred during the script execution.
The _doif control statement
can use the errlast or errworst
values as the condition to execute one or more commands.
See also the description for
comparing TestSmith variables.
| all commands
|
| errlast
| The error code of the last executed command.
This is always reset to 0 at the start of each new execution of the script.
Its value can be tested with a _doif statement.
See the description for
comparing TestSmith variables.
| _doif
|
| errworst
| The worst error code returned so far.
This is always reset to 0 at the start of each new execution of the script.
Its value can be tested with a _doif statement.
See the description for
comparing TestSmith variables.
| _doif
|
Miscellaneous Parameters ^
| Parameter Name
| Description
| Associated Commands
|
| remark
| A remark, of any length (but shorter is better) to output to
the logs during playback. The remark is output before the command
is executed (but after the Command Info line is output).
| all commands
|
| remark2
| A remark, of any length (but shorter is better) to output to
the logs during playback. This remark is output after the command
is executed. It is useful when you want to show the value
of a TestSmith variable that was set by the command, e.g.
reportTime myTime=: remark2='elapsed time is {myTime}' ;
| all commands
|
| popup
| A message, of any length (but shorter is better) to be displayed in a
pop-up "TestSmith Alert" dialog box. This will be shown before the command is executed.
Script execution will stop until the "OK" button on the dialog is clicked.
This parameter is intended for single-thread playbacks only.
If multiple playback threads are running the popup will not be displayed, but
instead a remark (REM) message will be written to the report file, preceded by the
string "(popup)".
Use this command for script debugging purposes only. Use the
remark parameter as an alternative for actual script runs.
| all commands
|
| message
| A text message describing the OK result
(for printOk) or ERR result
(for printErr).
This string should not exceed 2048 characters in length.
| printOk
printErr
|
| label
| A text label as an identifier. The label parameter is only necessary if a
_goto statement requires it. The
_goto statement will use the label to identify
which command to go back (or forward) to. Labels are case sensitive and should be unique.
Labels are searched for from the current command; once the end of the script is reached
searching continues from the beginning of the script until the current command is reached.
If the same label is used more than once, it is always the first encountered occurrence of
the label that will be used.
NOTE: Control Flow Statements
cannot contain a label parameter.
| all commands
|
| negate
| Use negate=1 to negate the result of a command.
OK results become ERR results, and visa-versa.
| all commands
|
| forceok
| Use forceok=1 to force any ERR result for that command
to be OK.
This parameter is useful, for example, when a command is immediately followed by a
_doif statement, which handles the failure, or
for any script where you want to restrict the ERR outputs to represent actual
failures of the script to complete.
Any Error codes issued by the command will still be respected, but alerts
will not be sent if this parameter is used.
| all commands
|
| alert
| Specify the type of alert to be sent. When used with the
sendAlert command an alert will
always be sent. When used with any other command an alert will only
be sent if an error occurs.
See TestSmith Alerts for detailed information on
how to set this parameter.
| sendAlert
all commands
|
| alertmsg
| A text string describing the alert.
This string should not exceed 2048 characters in length.
| sendAlert
|
| suppress
| Use this parameter to explicitly suppress certain log messages
for a single command. The value of suppress should be a string consisting
of one or more of the characters
o, e, f, w, i, d.
The characters can be in upper or lower case.
- o will suppress Flag (OK) messages.
- e will suppress Warning (ERR) messages.
- f will suppress Flag (FLG) messages.
- w will suppress Warning (WRN) messages.
- i will suppress Information (INF) messages.
- d will suppress Description (DESC) messages.
In addition the value all can be used to suppress all six message
types described above. Note that Remark (REM) messages cannot be suppressed.
| all commands
|
| script
| The full or relative path name of the *.smith script to be called.
Where 'relative' means in relation to the TestSmith.exe directory
or to the ROOTDIR (if specified).
| _call
|
| run
| The name of a Windows executable program to be used.
The file should be available on the system %PATH% or be
specified as a full drive:\path name.
| system
|
| reset
| Use reset=1 to reset the playback timer to 0.
| reportTime
|
| adjust
| Use adjust=1 to adjust the x,y coordinates of the command to be
relative to the coordinates of the item found with the last
valSeekItem command.
This parameter is recorded automatically (in most cases) for subsequent
msLClick commands on the same Windows object
that the valSeekItem action occurred on. It can also be added manually
(if required) to other mouse commands that follow the valSeekItem command.
Adjusting will always be done to the x,y point of the last sought item.
This parameter has no meaning in the absence of a
valSeekItem command.
See also the Seek Item documentation.
| ms commands
|
| value
| Specifies the index of the required row in the .csv file.
Data files are indexed starting from 1.
See setDataIndex for more information.
| setDataIndex
|
| op
| Use with a _doif statement to describe
the logical operator to be used. Two values are acceptable:
If any other value is used or if the op parameter is not present
the operator will default to AND.
The op parameter can only be specified once in a
_doif statement.
If only a single variable is being evaluated the op parameter is ignored.
If more than two variables are being evaluated each variable will be AND-ed
or OR-ed with all the others.
| _doif
|
| elapsed
| This is an 'out' parameter used only to collect the elapsed time value
from a reportTime command.
See Out Parameters for more information.
| reportTime
|
| grabfocus
| Force a mouse or menu command not to grab the focus of its window.
By default, a window focus is forced to the foreground before a mouse or
keyboard action. By setting grabfocus=0 the mouse or keyboard
event will be sent to whatever window or menu is in focus at the current time.
This is useful when, for example, a popup menu needs to be interacted with;
on some occasions the focus is forced to the window behind the menu, thus causing
the menu item to be by-passed. Using grabfocus=0 will avoid this.
| ms commands
kb commands
|
| const
| Only valid in conjunction with a variable declaration in a DECLARE_STR or
DECLARE_INT directive. The const keyword will force the value of the
variable to be constant (unchangeable). This constant quality does not take
effect until the first value is set for the variable.
| DECLARE_STR
DECLARE_INT
|
| Parameter Name
| Description
| Associated Commands
|
| user-defined
| Any user-defined variable name that has been declared with a
DECLARE directive.
See TestSmith Variables section
for full details of how to declare, set and use TestSmith variables.
| html commands
valEditText
valClipText
fRead
regRead
reportTime
setVar
_doif
|
str1
str2
str3
str4
int1
int2
int3
int4
counter
| Nine pre-named TestSmith variables
(four of type string and five of type integer) are implicitly declared
and can be used in the same way as user-defined variables.
| html commands
valEditText
valClipText
fRead
regRead
reportTime
setVar
_doif
|
Character Substitutions ^
|
Certain characters such as the space, the addition sign, etc. have special meaning
in a Smith script and need to be substituted with a %nn string.
TestSmith supports both hex substitutions and 2-character literal substitutions.
| | Character Name
| Character
| Hex Sub
| Literal Sub
| TestSmith Special Meaning
| | Tab (\t)
|
| %09
%__
| parameter separator
| | New Line (\n or \r\n)
|
| %0D
%nl
| parameter separator
| | Space
|
| %20
%--
| parameter separator
| | Number, Pound
| #
%23
%nu
%pd
comment character
| | Percent Sign
| %
%25
%pc
| character substitution marker
| Apostrophe,
Single Quotation
| '
%27
%ap
%sq
string quote character
| | Addition Sign
| +
%2B
%ad
1. parameter multi-line continuation character
2. variable addition or concatenation operator
| | Comma
| ,
%2C
%cm
| list separator character
| | Semi-colon
| ;
%3B
%sc
| end-of-command character
| | Acute Accent
| `
%60
%ac
| reserved for special use
| | Tilde
| ~
%7E
%ti
| reserved for special use
| |
Text containing too many of these substituted characters can become confusing to read.
Remembering these encodings when hand editing scripts can also be difficult.
TestSmith provides automatic encoding/decoding to overcome this problem.
See Encode Text Strings and
Translate Encoded Text for details.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
|
|