Run Options Global Properties
These global properties determine interactions with the system under test (SUT) when you run SenseTalk scripts with Eggplant Functional. The default values are appropriate for most situations. Keep in mind that the general SenseTalk global and local properties can also be useful in Eggplant Functional scripting. (For example, the colorFormat global property.)
In addition to the run options properties described below, SenseTalk includes additional application-specific properties for Eggplant Functional that generally affect how the application environment works with SenseTalk scripts.
Note that these values can be set as part of the Eggplant Functional Run preferences by going to Eggplant > Preferences, then selecting the Run tab. Changing the value of a property within a script affects that value for that runtime, but does not change the value set in the application preferences.
For general information about using local and global properties, see Local and Global Properties in SenseTalk.
The AdaptiveImageTolerance
Values: A positive number.
Default: 30
Behavior: Adjusts the Adaptive to Image search type's sensitivity to change between the captured image and potential image match. For more on search tolerance, see Tolerance.
Setting this value to 100 or more is likely to result in false-positive matches.
Example:
set the AdaptiveImageTolerance to 45
The AutoImageUpdateDiagnostics
Value: DynamicTolerance, AlternateTypes, ScalingSearch, DiscrepancySearch, CropEdges, OCRSearch, PriorLocation, OriginalLocation
Default: Uses the values as set in the Automatic Image Diagnostics section of the Diagnostics tab of Run Preferences. Note, however, that changes made in the preferences panel won't be reflected in the default value until after you restart the application.
Behavior: The AutoImageUpdateDiagnostics determines which search diagnostics are used for image searches when you use the Auto Update option for the Image Update panel. You can use this global property to change the diagnostics within a script run for specific searches, as required.
For information about how each search diagnostic works, see Image Diagnostics Selections. For information about the Image Update panel, see The Image Update Panel.
Example:
set the AutoImageUpdateDiagnostics to (DynamicTolerance, AlternateTypes, ScalingSearch, DiscrepancySearch, CropEdges, OCRSearch, PriorLocation, OriginalLocation)
Example:
// Stores the current settings of the global property in the variable 'OrigSettings'
put the AutoImageUpdateDiagnostics into OrigSettings
// Changes the setting for the global property
set the AutoImageUpdateDiagnostics to (OriginalLocation)
// Performs a search action using the new diagnostics settings
click image:"oContacts"
// Returns the global property to its original settings from the variable
set the AutoImageUpdateDiagnostics to OrigSettings
Related:
The AutoOCRUpdateDiagnosticsThe ImageUpdateDiagnosticsThe OCRUpdateDiagnostics
The AutoOCRUpdateDiagnostics
Value: CaseSensitive, IgnoreSpaces, TextDifference, ValidCharacters, ValidWords, DPI, Language
Default: Uses the values as set in the Automatic OCR Diagnostics section of the Diagnostics tab of Run Preferences. Note, however, that changes made in the preferences panel won't be reflected in the default value until after you restart the application.
Behavior: The AutoOCRUpdateDiagnostics determines which search diagnostics are used for OCR text searches when you use the Auto Update option for the OCR Update panel. You can use this global property to change the diagnostics within a script run for specific searches, as required.
For information about how each search diagnostic works, see OCR Diagnostics Selections. For information about the OCR Update panel, see The OCR Update Panel.
Example:
set the AutoOCRUpdateDiagnostics to (CaseSensitive, IgnoreSpaces, TextDifference, ValidCharacters, ValidWords, DPI, Language)
Example:
// Stores the current settings of the global property in the variable 'OrigSettings'
put the AutoOCRUpdateDiagnostics into OrigSettings
set the AutoOCRUpdateDiagnostics to (CaseSensitive, ValidCharacters)
click text:"Testplant"
// Returns the global property to its original settings from the variable
set the AutoOCRUpdateDiagnostics to OrigSettings
Related:
The AutoImageUpdateDiagnosticsThe ImageUpdateDiagnosticsThe OCRUpdateDiagnostics
The ForceScreenRefresh
Value: True or False.
Default: False.
Behavior: The ForceScreenRefresh determines whether Eggplant Functional refreshes the Viewer window after each command.
Example:
SetOption ForceScreenRefresh, true
the ForceScreenRefresh is rarely necessary, and dramatically slows down script execution. However, it might be helpful with a SUT that is generating a lot of screen artifacts or running software that does not display well through the VNC server.
The ImageSearchCount
Value: A positive integer.
Default: 7
Behavior: The ImageSearchCount determines the number of times Eggplant Functional scans the Viewer window searching for an image. When performing an image search that includes a WaitFor, Eggplant Functional automatically adjusts the ImageSearchDelay according to the ImageSearchCount. You can also use the ImageSearchTime Global Property to affect the search time for a section of image or text (OCR) searches.
Setting the ImageSearchCount to 1 causes image searches to look at only the current Viewer window, bypassing any ImageSearchDelay, screen refreshes, and mouse repositioning. This setting is the fastest way to perform a search, but it can be prone to failure.
The WaitFor command and WaitFor property can be used to set the ImageSearchCount indirectly for a single image search. The Eggplant Functional application fits as many scans as possible into the time specified by the WaitFor, at the frequency specified by the ImageSearchDelay.
Example:
// Sets the number of scans in the image search to 3 for any image searches that do not have an imageSearchTime override through WaitFor
SetOption ImageSearchCount, 3
Example:
// Sets the ImageSearchCount to 5, which indirectly changes the ImageSearchDelay to .36
SetOption ImageSearchCount, 5
// Scans for the image 28 times, based on the ImageSearchDelay of .36
WaitFor 10, "Dialog"
Example:
// Stores the current value for the imageSearchCount in a variable
set ISC to the imageSearchCount
// Sets the ImageSearchCount to 1
set the imagesearchcount to 1
// Scans for the image only once per execution of the imagefound() function
repeat until imagefound(image:"Footer")
// Scans for the image only once per execution of the imagefound() function
repeat until imagefound(image:"Footer")
// Provides error handling as a way to exit the repeat loop, exit the execution, fail the script, if it takes too long for the image to appear
if the repeatIndex is 10 then throw "Image not found", "Footer not found when scrolling."
SwipeUp // Swipes the screen up if the image isn't found
end repeat
// Returns the ImageSearchCount to the original value
set the imageSearchCount to ISC
Example:
// Performs scans = (120/the ImageSearchDelay + 1), rounded down to the nearest whole number
Click (ImageName:"Done_button", waitFor: 2 minutes)
Example:
// Performs scans = (10/the ImageSearchDelay + 1 scans), rounded down to the nearest whole number
WaitFor 10, "Done_Button"
A waitFor of 0 is a special value that sets the ImageSearchCount to 1.
Example:
// Scans for the image only once before executing the scrolling action
repeat until imagefound(image:"Footer",waitFor:0)
// Provides error handling to exit the repeat loop if the image is not found after an acceptable number of iterations
if repeatIndex() = 7 then throw "Image not found", "Image not found when scrolling."
SwipeUp
end repeat
Related:
The ImageSearchDelay
Value: Time (in seconds).
Default: 0.3
Example:
Behavior: The ImageSearchDelay determines the wait time between searches for an image.
Example:
Set the ImageSearchDelay to .6
Example:
// Increases the frequency of the scans to ensure detection of transient elements. Eggplant Functional attempts to search the area at this frequency, but if the area is large or you are searching for an image collection, etc., it automatically adjusts the frequency to allow each scan to complete.
Set the imageSearchDelay to 0.1
// Limits the search area to a subset of the screen, making a lower imageSearchDelay possible
WaitFor 1, (imageName:"RedLight", searchRectangle:("SignalUpperLeft","SignalLowerRight"))
Related:
The ImageSearchTime
Value: Time (in seconds).
Default: 1.8
Behavior: Determines the approximate amount of time Eggplant Functional spends on an image search or text (OCR) search before reporting a failure. It is influenced by the ImageSearchCount and the ImageSearchDelay.
The actual search time can be longer than the time specified by the ImageSearchTime. For example, using an ImageSearchTime of .3 and ImageSearchDelay of .3 is generally enough time for 2 scans to execute, the second of which begins after .3 seconds. The scan must then finish some time after the .3 second mark. In addition, when the ImageSearchTime is set to .3 and the ImageSearchDelay is set to .3, Eggplant Functional always attempts 2 scans, but if each scan takes longer than the ImageSearchDelay of .3 seconds, due to factors such as large screen size or large image collections, the frequency of the scans will automatically stretch to accommodate the factors, making the overall search take longer than the ImageSearchTime of .3 seconds.
The actual search time can also be shorter than the time specified by the ImageSearchTime. For example, using an ImageSearchTime of .5 and ImageSearchDelay of .5 is only enough time to initiate a maximum of 2 scans; a third scan could occur no sooner than at .6 seconds. If the second scan takes fewer than .2 seconds to execute, then the overall search time can be less than .5 seconds.
Example:
Set the ImageSearchTime to 5
Related:
The ImageUpdateDiagnostics
Values: StandardSearch, DynamicTolerance, AlternateTypes, ScalingSearch, DiscrepancySearch, OCRSearch, PriorLocation, OriginalLocation, CropEdges
Default: Uses the values as set in the Image Diagnostics section of the Diagnostics tab of Run Preferences. Note, however, that changes made in the preferences panel won't be reflected in the default value until after you restart the application.
Behavior: The ImageUpdateDiagnostics determines which search diagnostics are used for image searches when you use the Manual Update option for the Image Update panel. You can use this global property to change the diagnostics within a script run for specific searches, as required.
For information about how each search diagnostic works, see Image Diagnostics Selections. For information about the Image Update panel, see The Image Update Panel.
Example:
set the ImageUpdateDiagnostics to (StandardSearch, DynamicTolerance, AlternateTypes, ScalingSearch, DiscrepancySearch, CropEdges, OCRSearch, PriorLocation, OriginalLocation)
Related:
The AutoImageUpdateDiagnosticsThe AutoOCRUpdateDiagnosticsThe OCRUpdateDiagnostics
The KeyDownDelay
Value: Time (in seconds).
Default: 0.001
Behavior: The KeyDownDelay determines the wait time between key down and key up events sent to the SUT.
the KeyDownDelay does not govern the wait time between the separate KeyDown and KeyUp commands. Use the RemoteWorkInterval to affect the wait time between KeyUp and KeyDown.
The default value of the KeyDownDelay is quite fast, sometimes too fast for certain web browsers or apps, so you might find that occasionally characters used with a TypeText command aren't received by the SUT. Adjusting the KeyDownDelay to a speed appropriate for your SUT ensures that no characters are missed by the SUT. If the the KeyDownDelay does not help, try the NextKeyDelay as well.
Example:
SetOption KeyDownDelay, .05
Example:
set the KeyDownDelay to .1 // Releases each key after holding it down for .1 seconds
TypeText "www.yahoo.com",return // Both the key down and key up events are built into the TypeText command, so each key in the specified string, including the Return key, is affected by the KeyDownDelay
Related:
The MouseClickDelay
Value: Time (in seconds).
Default: 0.02
Behavior: The MouseClickDelay determines the wait time between mouseDown and mouseUp events sent to the SUT.
The default value of the MouseClickDelay is quite fast, sometimes too fast for certain apps, so you might find that your app does not respond to clicks or taps that use the default value. Adjusting the MouseClickDelay to a speed appropriate for your SUT ensures that the SUT recognizes the click or tap event.
Example:
set the MouseClickDelay to .5
The MouseDoubleClickDelay
Value: Time (in seconds).
Default: 0.01
Behavior: The MouseDoubleClickDelay determines the wait time between the end of the first click (mouseUp event) and the beginning of the second click (mouseDown event) of double-clicks sent to the SUT.
The default value of the MouseDoubleClickDelay is quite fast, sometimes too fast for certain apps, so you might find that your app does not respond to double-clicks or double-taps that use the default value. Adjusting the MouseDoubleClickDelay to a speed appropriate for your SUT ensures that the SUT recognizes the click or tap event.
Example:
Set the MouseDoubleClickDelay to .004
The MouseDragSpeed
Value: A number, 0 or greater.
Default: 10
Behavior: The MouseDragSpeed determines how fast the SUT's mouse is moved during a drag command. The value represents the number of pixels Eggplant Functional drags the SUT's mouse in each step. (Between steps, there is a pause the length of the MouseMoveDelay value.)
Example:
Set the MouseDragSpeed to 12
Example:
setOption mouseDragSpeed, 5 // Decreases the number of pixels (from the default) that Eggplant Functional drags the SUT's mouse in each step
Drag "ItemtoDrag"
Drop "DropLocation"
setOption mouseDragSpeed, 10
Related:
The MouseMoveDelayGlobal PropertyThe MouseMoveModeGlobal PropertyThe MouseMoveSpeedGlobal Property
The MouseMoveDelay
Value: Time (in seconds).
Default: 0.01
Behavior: The MouseMoveDelay determines the wait time between each step of a mouse move on a SUT.
Example:
Set the MouseMoveDelay to .06
Related:
The MouseDragSpeedGlobal PropertyThe MouseMoveModeGlobal PropertyThe MouseMoveSpeedGlobal Property
The MouseMoveMode
Value: 0, 1, or 2
Default: 0
Behavior: The MouseMoveMode determines the path a mouse takes to move from one location to the next. Options are:
- 0: The mouse moves in a straight line.
- 1: The mouse moves horizontally, then vertically.
- 2: The mouse moves vertically, then horizontally.
If the MouseMoveSpeed value is 0, the mouse jumps to the next location instantly, and the MouseMoveMode value is irrelevant.
Example:
SetOption MouseMoveMode, 1
Example:
Click "ObjectsMenu"
put the MouseMoveMode into MMM
set the MouseMoveSpeed to 10
set the MouseMoveMode to 2 // Because the mouseMoveSpeed has been changed from 0, the mouseMoveMode, when set to 2, causes the mouse cursor to move to each new location by first moving vertically, and then horizontally
Moveto "Circles"
Moveto text:"Radius"
Click "Value"
set the MouseMoveMode to MMM
set the MouseMoveSpeed to 0
Related:
The MouseDragSpeedGlobal PropertyThe MouseMoveDelayGlobal PropertyThe MouseMoveSpeedGlobal Property
The MouseMoveSpeed
Value: A number, 0 or greater.
Default: 0
Behavior: The MouseMoveSpeed determines how fast the SUT mouse moves in the Viewer window. The value represents the number of pixels Eggplant Functional moves the SUT mouse in each step. (Between steps, there is a pause the length of the MouseMoveDelay value.)
With the default value of 0, the mouse jumps from its current position to the next point in one step.
Some systems (particularly certain Linux systems), applications (such as Flash applications), and VNC technologies (particularly KVM-over-IP devices) have trouble tracking or recognizing the mouse under the default the MouseMoveSpeed value. For these environments, start with a value of 10, then reduce the value as necessary until you find one that works. Conversely, if 10 is slow enough, you can try increasing the value to see how fast the mouse can move before the SUT can no longer track it.
Example:
SetOption MouseMoveSpeed, 10
Related:
The MouseDragSpeedGlobal PropertyThe MouseMoveDelayGlobal PropertyThe MouseMoveModeGlobal Property
The NextKeyDelay
Value: Time (in seconds).
Default: 0.01
Behavior: The NextKeyDelay determines the wait time between keystrokes sent to the SUT.
The default value of the NextKeyDelay is quite fast, sometimes too fast for certain web browsers or apps, so you might find that occasionally characters used with a TypeText command aren't received by the SUT. Adjusting the NextKeyDelay to a slower speed appropriate for your SUT ensures that no characters are missed by the SUT. If adjusting the NextKeyDelay does not resolve the issue, try changing the KeyDownDelay as well.
Example:
SetOption NextKeyDelay, .08
Example:
set the nextKeyDelay to .1
TypeText "812903812903801983012830912830912830193801238"
Related:
The OCRUpdateDiagnostics
Value: StandardSearch, CaseSensitive, IgnoreSpaces, TextDifference, ValidCharacters, ValidWords, DPI,Language
Default: Uses the values as set in the OCR Diagnostics section of the Diagnostics tab of Run Preferences. Note, however, that changes made in the preferences panel won't be reflected in the default value until after you restart the application.
Behavior: the OCRUpdateDiagnostics determines which search diagnostics are used for OCR text searches when you use the Manual Update option for the OCR Update panel. You can use this global property to change the diagnostics within a script run for specific searches, as required.
For information about how each search diagnostic works, see OCR Diagnostics Selections. For information about the OCR Update panel, see The OCR Update Panel.
Example:
set the OCRUpdateDiagnostics to (StandardSearch, CaseSensitive, IgnoreSpaces, TextDifference, ValidCharacters, ValidWords, DPI, Language)
Related:
The AutoImageUpdateDiagnosticsGlobal PropertyThe AutoOCRUpdateDiagnosticsGlobal PropertyThe ImageUpdateDiagnosticsGlobal Property
The PreciseImageTolerance
Value: An integer, 0-255.
Default: 1
Behavior: Sets the default tolerance used by the Precise to Image search type. For more on search tolerance, see Tolerance.
Example:
Set the PreciseImageTolerance to 3
The RemoteWorkInterval
Value: Time (in seconds).
Default: 0.7
Behavior: The RemoteWorkInterval determines the minimum time Eggplant Functional allows for the SUT to perform a task before sending the next event from a script. This setting is an important timing parameter for regulating the overall speed of interactions with the SUT.
Example:
SetOption RemoteWorkInterval, 1
Example:
// Shortens the minimum delay allowed between each action (Click, TypeText) to .1 seconds
set the remoteworkinterval to .1
Click "FirstNameField"
TypeText "Bob"
Click "LastNameField"
TypeText "Anderson"
Click "AgeField"
TypeText "33"
The SendShiftForCaps
Value: Yes, Always, and Never.
Default: Yes
Behavior: The SendShiftForCaps determines whether ShiftKeyDown is used for capital letters sent to the SUT.
- Yes: Sends the Shift key to type capital letters in commands that do
notinclude a modifier-key parameter. For example,TypeText AltKey & "S"would not send a Shift to generate a capital S because doing so would change the result fromAlt+stoShift+Alt+s. However,TypeText "Seattle"wouldsend a Shift to type a capital S. - Always: Sends the Shift key to the SUT whenever a capital letter appears in a
TypeTextparameter. - Never: Never sends Shift to type a capital letter. (You can still send the Shift key by specifically passing the
ShiftKeyparameter.)
Example:
Set the SendShiftForCaps to yes
The ShouldRepositionMouse
Values: True or false.
Default: False
Behavior: the ShouldRepositionMouse determines whether the SUT mouse moves to the lower-right corner of the Viewer window (or the coordinates of the RepositionPoint) during image searches. (Repositioning the mouse prevents it from obscuring images elsewhere.) the ShouldRepositionMouse is particularly relevant when there is a mouse-over event, such as a pop-up menu or tooltip, that could obscure the UI element you are validating.
Example:
Set the ShouldRepositionMouse to True
Example:
setoptions (shouldrepositionmouse:true,repositionpoint:(10,10)) // In one command, enables the ShouldRepositionMouse and changes the RepositionPoint to coordinate location (10,10)
WaitFor 5, "DesktopIcon"
Example:
// With shouldrepositionmouse set to false, the cursor would stay hovering over the account menu element which creates a popup menu, obscuring a portion of the UI.
//This behavior might hide the next element you are searching for. Setting it to true allows Eggplant Functional to automatically move the cursor to the RepositionPoint
//(the lower-right corner of the screen, by default) in the event that any images or text (OCR) can't be found on the first scan for the element.
set the shouldrepositionmouse to true
Click "UniversalMenu_Account"
Click "Account Details"
The StandardImageTolerance
Value: An integer, 0-255.
Default: 45
Behavior: Sets the default tolerance used by the Tolerant to Background image search type. For more on search tolerance, see Tolerance.
The default values are appropriate for most situations. Practical values can range from 0 to 100, but a value of 80 or higher is likely to generate false positive matches.
Example:
Set the StandardImageTolerance to 50
Example:
SetOption PreciseImageTolerance, 4
The SwipeSpeed
Value: A number, 0 or greater.
Default: 40
Behavior: This global property controls the speed at which swipe events occur. The value represents the number of pixels Eggplant Functional drags the SUT mouse in each step.
Example:
Set the SwipeSpeed to 3
Example:
// Stores the current SwipeSpeed into a variable
put the SwipeSpeed into SS
put 10 into the SwipeSpeed
SwipeUp
// Returns the SwipeSpeed to the value stored in the variable
put SS into the SwipeSpeed
SwipeLeft
Example:
// Makes each swipe shorter, making the swiping more predictable
set the swipespeed to 2
// WaitFor:0 tells Eggplant Functional to scan for the image only once instead of the default of seven times
repeat until imagefound(image:"MenuOption",waitFor:0)
// Uses a conditional statement to throw an exception and stop the execution if the repeat loop repeats 4 times
if the counter is 4 then // Checks which iteration the repeat loop is on
throw "Image not found.", "Image not found while scrolling."
end if
SwipeUp
wait 2 // Waits a short amount of time to allow the screen to settle after the swipe occurs
end repeat
set the swipespeed to 40 // Sets the swipespeed to 40, which is the default
The WebElementDisplay
Value: Short or long.
Default: Long
Behavior: This global property controls how WebElement objects display in the results log of a run or when called in a script, i.e., put myElement. If an element is not available in the current page context, the WebElement object displays in short format even if the WebElementDisplay is set to long.
Example:
set the WebElementDisplay to short