Skip to main content
Version: 23.3

Image References

There are several ways to refer to images as command and function parameters:

Image Name​

Image names are text strings, and must be enclosed in quotation marks. File extensions are optional.

Example:

Click "ImageOne"
Click "ImageOne.jpg"

Image Collection​

An Image Collection is a folder of related images that are all acceptable versions of a basic image. For example, an Image Collection might contain a "normal" image of a button, a selected version, and a disabled version.

Any image folder in your suite can be used as an Image Collection; just keep in mind that Eggplant Functional looks for every image in the Image Collection, so a very large folder could slow down your script execution and cause Eggplant Functional to find matches you are not interested in.

Image Collections are text strings, such as image names. To learn how to create an image collection see Creating an Image Collection.

Example:

Click "SaveButton"
note

The functions ImageSize() and ImageHotSpot() cannot have Image Collections as parameters.

Collection Filters​

You can use the global property the CollectionFilter to narrow down the images Eggplant Functional looks for within a script, by name, image description, or both.

Example:

Set the CollectionFilter to {Name: "German"}
Set the CollectionFilter to {Name: "German", Description: "New version"}

In the first example, Eggplant Functional would limit searches to images with the string "German" in the image name. In the second example, it would limit searches to images with "German" in the name, and "New version" in the image description (as recorded in the Images pane of the Suite Editor).

note

For filtering purposes, an image's subpath within an Image Collection is considered part of its name.

Image Property List​

An image property list refers to a pre-existing image or Image Collection with the ability to override its default properties. Every image property list must contain the ImageName property, and may contain any additional properties from the following list.

  • ImageName: File name. The name of the image file. (Required.)

  • HotSpot: Coordinate pair. The image's hot spot, with coordinates relative to the top-left corner of the image.

  • WaitFor: Number. The maximum time Eggplant Functional waits for the given image to appear on the SUT. The default unit of time is seconds; you can also specify minutes.

  • SearchType: Tolerant of Background, Smoothed for Text, and Adaptive to Image are the most common image search types. Other less frequently used types such as Precise to Pixel, Pulsing to Element, and Smooth and Pulsing are available as well. For full explanations of the different search types and their capabilities, see Choosing the Best Search Type in Image Capture Best Practices.

    note

    The search type Smoothed for Text was formerly called Smooth.

  • Pulsing: Boolean. Whether or not the search type allows for a pulsing image.

  • Tolerance: Integer. A number that represents the acceptable color difference between pixels in an image and a match in the Viewer window. You can set a single value that is used for red, green, and blue, or three separate values separated by commas.

  • Discrepancy: Integer. The percentage of pixels (with a percent sign) or number of pixels (with no percent sign) by which the image and a match in the Viewer window can differ.

    note

    Discrepancy can be slow to use and can result in false positive matches. Preferable approaches include setting the Search Type to Smoothed for Text in the Image Update panel, cropping the image using the Image Editor, or creating an Image Collection that includes several acceptable versions of a basic image. You can also capture a new image if the current image can only be found using a discrepancy search.

  • CollectionFilter: Text string. For Image Collections only, CollectionFilter limits the images that are searched for within an Image Collection. (For more information, see Collection Filters, above.)

  • ClipRectangle: Rectangle.. With (0,0) being the top-left corner of the image, the cliprectangle is a pair of coordinates that define a rectangle within the captured image. Only the pixels inside this rectangle are considered for image matches.

  • SearchRectangle: Rectangle defined by a coordinate pair (top left corner, bottom right corner). With (0,0) being the top-left corner of the screen, the SearchRectangle is a pair of coordinates that define a rectangle on the screen of the SUT. Eggplant Functional only looks for this image within the defined rectangle.

  • Rotate: Number. Searches for an image at a given number of degrees of rotation from the angle at which it was captured. See Image Rotation.

Example:

Click {ImageName: "CloseButton", HotSpot: [10, 23], SearchType: "Tolerant"}

Image Scaling​

By default, Eggplant Functional searches for all images at their native resolution (a scale of 1.0). You can modify the scale in several ways, including by scaling factors, by size, and dynamically. See Finding Images for specific usage examples.

Character Collections​

Character collection searches are a special form of image search to be used when OCR cannot find custom fonts on a SUT. Perhaps these fonts are being used along with unusual backgrounds that make OCR searches even more challenging. To overcome problems such as these, use a character collection search instead of an OCR search. See Working with Character Collections for more information.

Last updated on