Skip to main content

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.

note

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:

put the AutoImageUpdateDiagnostics into OrigSettings // Stores the current settings of the global property in the variable 'OrigSettings'
set the AutoImageUpdateDiagnostics to (OriginalLocation) // Changes the setting for the global property
click "oContacts" // Performs a search action using the new diagnostics settings
set the AutoImageUpdateDiagnostics to OrigSettings // Returns the global property to its original settings from the variable

Related:

  • The AutoOCRUpdateDiagnostics
  • The ImageUpdateDiagnostics
  • The 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:

put the AutoOCRUpdateDiagnostics into OrigSettings // Stores the current settings of the global property in the variable 'OrigSettings'
set the AutoOCRUpdateDiagnostics to (CaseSensitive, ValidCharacters)
click text:"Testplant"
set the AutoOCRUpdateDiagnostics to OrigSettings // Returns the global property to its original settings from the variable

Related:

  • The AutoImageUpdateDiagnostics
  • The ImageUpdateDiagnostics
  • The 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
note

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.

note

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.

note

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:

SetOption ImageSearchCount, 3 // Sets the number of scans in the image search to 3 for any image searches that do not have an imageSearchTime override through WaitFor

Example:

SetOption ImageSearchCount, 5 // Sets the ImageSearchCount to 5, which indirectly changes the ImageSearchDelay to .36
WaitFor 10, "Dialog" // Scans for the image 28 times, based on the ImageSearchDelay of .36

Example:

set ISC to the imageSearchCount // Stores the current value for the imageSearchCount in a variable
set the imagesearchcount to 1 // Sets the ImageSearchCount to 1

repeat until imagefound(image:"Footer") // Scans for the image only once per execution of the imagefound() function
  if the repeatIndex is 10 then throw "Image not found", "Footer not found when scrolling." // 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
  SwipeUp // Swipes the screen up if the image isn't found
end repeat

set the imageSearchCount to ISC // Returns the ImageSearchCount to the original value

Example:

Click (ImageName:"Done_button", waitFor: 2 minutes) // Performs scans = (120/the ImageSearchDelay + 1), rounded down to the nearest whole number

Example:

WaitFor 10, "Done_Button" // Performs scans = (10/the ImageSearchDelay + 1 scans), rounded down to the nearest whole number
note

A waitFor of 0 is a special value that sets the ImageSearchCount to 1.

Example:

repeat until imagefound(image:"Footer",waitFor:0) // Scans for the image only once before executing the scrolling action
  if repeatIndex() = 7 then throw "Image not found", "Image not found when scrolling." // Provides error handling to exit the repeat loop if the image is not found after an acceptable number of iterations
  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:

Set the imageSearchDelay to 0.1 // 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.
WaitFor 1, (imageName:"RedLight", searchRectangle:("SignalUpperLeft","SignalLowerRight")) // Limits the search area to a subset of the screen, making a lower imageSearchDelay possible

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.

note

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.

note

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 AutoImageUpdateDiagnostics
  • The AutoOCRUpdateDiagnostics
  • The 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.

note

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.

tip

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.

tip

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.

tip

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 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 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.
note

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 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.

tip

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 NextKeyDelay​

Value: Time (in seconds).

Default: 0.01

Behavior: The NextKeyDelay determines the wait time between keystrokes sent to the SUT.

tip

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 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:

set the remoteworkinterval to .1 // Shortens the minimum delay allowed between each action (Click, TypeText) to .1 seconds
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 not include 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 from Alt+s to Shift+Alt+s. However, TypeText "Seattle" would send a Shift to type a capital S.
  • Always: Sends the Shift key to the SUT whenever a capital letter appears in a TypeText parameter.
  • Never: Never sends Shift to type a capital letter. (You can still send the Shift key by specifically passing the ShiftKey parameter.)

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:

set the shouldrepositionmouse to true // 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.
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.

note

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:

put the SwipeSpeed into SS // Stores the current SwipeSpeed into a variable
put 10 into the SwipeSpeed
SwipeUp
put SS into the SwipeSpeed // Returns the SwipeSpeed to the value stored in the variable
SwipeLeft

Example:

set the swipespeed to 2 // Makes each swipe shorter, making the swiping more predictable
repeat until imagefound(image:"MenuOption",waitFor:0) // WaitFor:0 tells Eggplant Functional to scan for the image only once instead of the default of seven times
  // 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
Last updated on