locate method

Class: EyesPlatform: ProtractorLanguage: JavaScript SDK:

Use this method to search the current browser viewport for one or more graphics regions defined by visual locators.


Call syntax

let regions = eyes.locate({ locatorNames: ["locA", "locB"], firstOnly: false });


<TLocator extends string>(settings:VisualLocatorSettings<TLocator>):Promise<Record<TLocator,RegionPlain[]>>


A literal object that defines the required visual locator names and whethere a single or all instances of each locator should be found. See the example below for more details.

Return value

Type: Promise<Record<TLocator,RegionPlain[]>>

Returns a mapping between the names passed in the locatornames field passed as a parameter and the regions in the viewport where the graphic images defined by those locator names were detected. If the firstOnly parameter is passed and has a value of true then only the 1st result found is retuned.

If the image of a particular locator name is not found in the viewport, the locator is mapped to a zero length array. If a locator name is passed, and a locator of that name has not been defined on the Eyes server, the returned locator will be mapped to a value of null instead of an array.

and each value is an object that contains the text found and its bounding rectangle.

Type definitions

Used to describe a position and rectangular region in an image. RegionPlain is defined as: LocationPlain&RectangleSizePlain


The article Visual locators describes in detail how to associate locator names with graphic images and how to search for instances of the graphic in the browser viewport. The example below is a briefer description of how to search for instances of the locator graphics.