Found-Image and Found-OCR Information Functions

The functions in this section return additional information about the last visual element (when using Find by Description searches), captured image, or optical character recognition (OCR) text match 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

tip

You can use AI searches with this function.
For more information, see Find by Description.

Behavior: Returns a property list for a single Find by Description search, captured image search, 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:

• Description property:
  • For Find by Description searches, this is the description you provided in your script.
  • For image searches, this is the image description in the Suite Editor Info panel.
  • This property is not returned for OCR searches.
• ImageLocation property:
  • For Find by Description searches, this is the location where the described element was found.
  • For image searches, this is the coordinates of the image found using the ImageLocation function.
  • For OCR searches, this is the location the text was found.
• ImageRectangle property:
  • For Find by Description searches, this is the rectangle coordinates for the found element. For these searches, the ImageRectangle is automatically fitted around the element as it appears on the SUT.
  • For image searches, the rectangle coordinates of the image found using the ImageRectangle function.
  • For OCR searches, this is the rectangle coordinates for the found text. For these searches, the ImageRectangle is automatically fitted around the text as it appears on the SUT.

Parameters: None; refers to the last image found.

Returns: An element (for Find by Description searches), captured image reference, or OCR property list. For example:

A Find by Description search returns:

{description:"the star icon", ImageLocation:[163,602], ImageRectangle:[141,582,186,622]}

A captured image search returns:

{CaptureDate:"2026-05-09 16:45:28 +0000", CaptureHost:"Tutorial Connection", CaptureLocation:[140,580], CaptureScreenSize:["427","640"], Description:"", HotSpot:[20,16], ImageLocation:[160,596], ImageName:"Favorites", ImagePath:"/Users/elizsimo/Documents/Eggplant Suites/Test.suite/Images/Favorites.png", ImageRectangle:[140,580,182,620], ImageSize:[42,40], Pulsing:"False", Scale:1, SearchType:"Tolerant of Background"}

An OCR search returns:

{CaseSensitive:"No", Contrast:"Off", DPI:"72", EnableAggressiveTextExtraction:"No", EnhanceLocalContrast:"No", FoundText:"Downloads", IgnoreNewLines:"No", IgnoreSpaces:"No", ImageLocation:[372,630], ImageRectangle:[338,625,406,635], Language:"English", text:"Downloads", TextPlatform:"Generic OCR", TextStyleName:"Default", ValidCharacters:"", ValidPattern:"", ValidWords:""}

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.

Example: Using a Find by Description Search:

Use an AI-powered Find by Description search to locate the "Contact Us" form on a website, and record the information about the found location:

Waitfor 4, description:"Contact Us form"
log foundImageInfo()

Example: Using an OCR Text Search:

Search for and click on a text string, and then print the foundImageInfo to the Run window:

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

Example: Using a Captured Image Search:

Wait for an image, and then log just its description:

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

Example: Storing the Location of a Captured Image:

This example stores the contents of the foundImageInfo for reference at a later time:

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

Example: Confirming the Location Where a Captured Image Was Found:

This example confirms that the location where an image was captured and the location where it was found are the same:

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: Searching for Multiple Captured Images:

See which image appears, and then click it, using foundImageInfo:

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: Gathering foundImageInfo for a Captured Image:

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 a script called ImageTrackingOverrides, instead of using the built-in commands
DoubleClick "BrowserIcon"
Click "AddressBar"
put imageUsage into file "C:\Users\Carrie\Desktop\myImageUsage.txt" -- Writes the contents of 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

tip

You can use AI searches with this function.
For more information, see Find by Description.

Behavior: Returns screen coordinates for the last element found using Find by Description, or the hot spot of the last captured image or text (OCR) that was found on the SUT.

Parameters: None; refers to the last element (using Find by Description), captured image, or text (OCR) found.

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

Example: Using a Find by Description Search:

Use an AI-powered Find by Description search for the shopping cart to display on a web page, and then log its location:

Waitfor 3, description:"Shopping cart icon"
log foundImageLocation()

Examples: Using Captured Image Searches:

Locate an element using a captured image, and then click the hot spot location of the image, where it was found:

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

Click, and then Drag and Drop to select a node, using captured images with foundImageLocation:

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

Example: Using an OCR Text Search:

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

FoundImageNumber Function

tip

You can use AI searches with this function.
For more information, see Find by Description.

Returns: One number, representing the ordinal position of a found element (if using Find by Description), captured image, or text (OCR) in the parameter list of a command or function. For example: 3

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

Example: Using Captured Image Searches:

Confirm that a page is loading in the order you expect, with the Welcome message image displaying first:

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 a warning message

Example: Using a Find by Description Search:

The same can be confirmed using a combination of AI-powered Find by Description searches and an image search:

Waitfor 10, (description:"Welcome message"), (description:"sign out button"), (imagename:"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 a warning message

Example: Using OCR and a Captured Image Search Together:

Record the position of the found image:

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.