Found-Image and Found-OCR Information Functions

The functions in this section return additional information about the last image or text (OCR) search that was found on the system under test (SUT). These functions can be especially helpful if, for instance, you are using image collections and need to determine which image in the collection was found, or if you need to determine the scale at which an image was found when working with multiple scales.

FoundImageInfo Function

Behavior: Returns a property list for a single image or OCR search, or a list of property lists for multiple references. Depending on the data that is available, the list can contain the properties listed in Image Properties or OCR Properties, as well as the following properties:

For Image Searches

• Description: The image description in the Suite Editor Info panel.
• ImageLocation: The coordinates of the image found using the ImageLocation function.
• ImageRectangle: The rectangle coordinates of the image found using the ImageRectangle function.

note

In some cases you might see the foundImageInfo function return Smoothed for Text as the search type, when Tolerant of Background was originally set. This occurs when the search is conducted using a Scale other than 1.

Parameters: None; refers to the last image found.

Returns: An image or OCR property list. For example:

Image search returns:

(CaptureDate:"2016-09-09 13:02:53 -0600", CaptureHost:"Windows", CaptureLocation:(305,270), CaptureScreenSize:(1024,768), Description:"", HotSpot:(41,14), ImageLocation:(346,284), ImageName:"WelcomeMessage", ImagePath:"C:/Users/Carrie/Documents/Suites/mySuite.suite/Images/WelcomeMessage.png", ImageRectangle:(305,270,387,298), ImageSize:(82,28), ImageTolerance:"53", Pulsing:"False", Scale:"1", SearchType:"Smooth")

OCR search returns:

(CaseSensitive:"No", Contrast:"Off", IgnoreSpaces:"No", ImageLocation:(351,283), ImageRectangle:(319,277,384,290), Language:"English", searchrectangle:(230,242,504,371), text:"TestPlant", TextPlatform:"Generic OCR", validcharacters:"TestPlant")

Example:

Click text:"Single Sign-On"
put FoundImageInfo() // Prints the return of FoundImageInfo for the previously successful image or OCR search

Example:

WaitFor 10, "WelcomeMessage"
log the FoundImageInfo's description // Logs the content of the image's description

Example:

click "SignInButton"
set clickedImage to FoundImageInfo()'s imageName // Stores the name of the last image found into the variable called clickedImage

Example:

WaitFor 10, "WelcomeMessage"
set myImageInfo to the FoundImageInfo // Stores the return from FoundImageInfo into a variable called myImageInfo
assert that the CaptureLocation of myImageInfo equals the ImageLocation of myImageInfo // Asserts with an exception that the CaptureLocation and ImageLocation of the found image "WelcomeMessage" are equal

Example:

WaitFor 60, "Username","Yes" // Alternates searches for two images ("Username" and "Yes") for up to 60 seconds
put the short name of file the foundimageinfo's imagepath into FoundImage // Stores the name of the first image found by the WaitFor command

If FoundImage is "Username" then
  Click "Username"
else if FoundImage is "Yes"
  Click "Yes"
Click {image:"Username",waitFor:10}
End If

Example:

This example uses overrides to gather FoundImageInfo each time you perform an image search.

Main script:

global ImageUsage // Declares the global variable in the main script that gathers usage for each image searched for
start using "ImageTrackingOverrides" // Tells Eggplant to start using the set of override commands inside ImageTrackingOverrides script, instead of using the built-in commands
DoubleClick "BrowserIcon"
Click "AddressBar"
put imageUsage into file "C:\Users\Carrie\Desktop\myImageUsage.txt" // Writes the contents imageUsage out to a file at the end of the main script execution

ImageTrackingOverrides script:

to Click // The override command should have the same name as the command you are overriding
pass message and continue // Passes the message, which is the name of the handler ("Click", in this case) as well as any parameters passed into the handler, if applicable
GatherImageInfo // Calls the reusable custom command GatherImageInfo, defined below
end Click
to DoubleClick
  pass message and continue
  GatherImageInfo
end DoubleClick
// Creates the custom GatherImageInfo command
on GatherImageInfo
  global ImageUsage // Declares the global variable in the command
  set myImageInfo to FoundImageInfo()
  put myImageInfo.ImageName&comma&the short name of file myImageInfo.ImagePath&CRLF after ImageUsage
  // Takes the name of the image reference and the actual found image and adds it and a carriage return line feed to the end of global variable ImageUsage
end GatherImageInfo

FoundImageLocation Function

Behavior: Returns screen coordinates for the hot spot of the last image or text (OCR) that was found on the SUT.

Parameters: None; refers to the last image or text (OCR) found.

Returns: Coordinates. For example: (195,137)

Example:

If ImageFound("OKButton") then click the FoundImageLocation // Clicks the location returned by FoundImageLocation

Example:

WaitFor 30, text:"Sign Out"
set SignOutButtonLocation to FoundImageLocation() // Stores the location of the center of the successful OCR search in a variable called SignOutButtonLocation
ValidateAccountConfiguration // Runs a script called ValidateAccountConfiguration
Click SignOutButtonLocation // Clicks the location stored in SignOutButtonLocation

Example:

Click "SelectNode"
Wait .5 // Depending on the value of the RemoteWorkInterval, a short wait might be required to prevent the Click and Drag from behaving together like a DoubleClick
Drag FoundImageLocation() // Begins a Drag at the location of the hot spot of SelectNode
Drop "EndNode" // Ends the drag at the location of the hot spot of EndNode

FoundImageNumber Function

Returns: One number, representing the image’s or text's (OCR) ordinal position in the parameter list of a command or function. For example: 3

Parameters: None; refers to the last image or text (OCR) found.

Example:

WaitFor 10, "WelcomeMessage", "SignOutButton", "CompanyLogo"
If the FoundImageNumber is not 1 then LogWarning "The page loaded but not in the expected order." // If SignOutButton or CompanyLogo are found first, then FoundImageNumber returns 2 or 3, respectively, and triggers the statement to log the warning message

Example:

Click {text:"Single Sign-On"}, "SignOut"
log foundImageNumber() // Logs the ordinal position number of the found element

FoundImageName Function (Deprecated)

note

FoundImageName is deprecated. Instead, use the FoundImageInfo function.

Examples:

Put FoundImageInfo()'s imageName -- This returns the image name.
Put FoundImageInfo()'s imagePath -- This returns the entire file path, including the image name.

Behavior: Returns the name of the last image found.

Parameters: None; refers to the last image found.

Returns: Image name.