waitForImage

ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion])

This function waits for an image as specified by imageFile to appear on the screen, by repeatedly calling ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) until a timeout is reached. In case of success, the location of the image as found on the screen will be returned as a ScreenRectangle. Interaction functions like mouseClick(screenPoint, modifierState, button), doubleClick(screenPoint, modifierState, button) or tapObject(screenPoint, modifierState) can be used to click or tap on the detected location.

If a directory is passed for imageFile, it is treated as an Image Group.

The behavior of Image Search functions (findImage, waitForImage, and test.imagePresent), can be customized through additional parameters passed to the optional parameterMap of key-value pairs, where a key can be one of these:

• occurrence - The occurrence index. By default the first match (with index 1) will be selected. Index values 2 and higher will select consecutive matches.
• interval - Number of milliseconds to wait in between image search retries. The default is 1000 (1 second).
• timeout - Amount of time in milliseconds to search for an image before reporting that the image is not found. The default is 20000 (20 seconds).
• tolerant - Boolean switch that enables tolerant image search mode. In this mode some differences between the template image and the desktop screenshot are allowed. The default value is the value of testSettings.imageSearchTolerant property. The comparison algorithm used is Correlation.
• threshold - Threshold on the correlation between template image and a desktop screenshot, expressed as a percentage. A correlation higher than the threshold is considered a match against the template image. Usable values for this parameter usually fall between 99.0 and 100.0. The default value is the value of the testSettings.imageSearchThreshold property. This parameter is ignored if the tolerant parameter is set to false.
• multiscale - Boolean switch that enables scaled image search mode. In this mode the template image is expanded into a series of images of different sizes. Those image are subsequently used as template images for the image search. The default value is the value of the testSettings.imageSearchMultiscale property. This parameter is ignored if the tolerant parameter is set to false.
• minScale - Lower bound on the template image series sizes, expressed as a percentage. The resized template image sizes will span between minScale and maxScale of the original image size. The default value is the value of the testSettings.imageSearchMinScale property. This parameter is ignored if either the tolerant or the multiscale parameters are set to false.
• maxScale Upper bound on the template image series sizes, expressed as a percentage. The resized template image sizes will span between minScale and maxScale of the original image size. The default value is the value of the testSettings.imageSearchMaxScale property. This parameter is ignored if either the tolerant or the multiscale parameters are set to false.
• message - An optional detailed description (of type string) added to the test result no matter whether the test passed or failed, much like message argument of Boolean test.compare(value1, value2).

When the search image contains transparent or semi-transparent pixels, this can affect comparisons in the following ways:

• Fully transparent pixels act as a mask, meaning the image search will ignore these pixels when matching the rest of the reference image against the screenshot.
• Semi-transparent pixels are handled differently depending on the image-search mode.
  • If tolerant is true, the semi-transparent pixels are binarized, meaning that any semi-transparent pixels with a transparency of < 127 are considered 'non-transparent' and used in the same way as actual non-transparent pixels, while pixels with transparency >= 127 are considered fully transparent and thus used for masking purposes.
  • If intolerant, the transparency value is used to allow semi-tolerant matching: the higher the transparency value, the higher the allowed color deviation of each semi-transparent pixel from its reference pixel.

# Click on icon.png
mouseClick(waitForImage("icon.png"))

// Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"))

# Click on icon.png
invoke mouseClick [waitForImage "icon.png"]

By default this function will repeatedly grab the screen content until successful or until 20 seconds have passed. Longer (or shorter) waiting periods can be set in milliseconds via a timeout value passed through the parameterMap. In order to perform a single image search, use the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) function.

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence": 2, "timeout": 10000})

// Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {occurrence: 2, timeout: 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}))

# Click on second icon.png, wait maximum 10 seconds
invoke mouseClick [waitForImage "icon.png" {occurrence 2 timeout 10000}]

The matching algorithm performs a pixel-by-pixel color value comparison. The screen content and sub-image content therefore have to match 100% unless the tolerant search mode is enabled.

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {'tolerant': True,
                                     'threshold': 99.7,
                                     'multiscale': True,
                                     'minScale': 100.0,
                                     'maxScale': 150.0})

// Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant: true,
                                     threshold: 99.7,
                                     multiscale: true,
                                     minScale: 100.0,
                                     maxScale: 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant => true,
                                     threshold => 99.7,
                                     multiscale => true,
                                     minScale => 100.0,
                                     maxScale => 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {"tolerant" => true,
                                     "threshold" => 99.7,
                                     "multiscale" => true,
                                     "minScale" => 100.0,
                                     "maxScale" => 150.0}))

# Click on icon.png, found with tolerance of 99.7
invoke mouseClick [waitForImage "icon.png" {tolerant true \
                                            threshold 99.7 \
                                            multiscale true \
                                            minScale 100.0 \
                                            maxScale 150.0}]

In case a searchRegion is specified as the last argument, the search is performed only within the area corresponding to it. The search region can be an AUT object, a ScreenRectangle object or an array of such objects. It can also be a special string value "all", in which case all top-level objects are used.

The searchRegion can also be an Image Object object. In such case no new screenshots are taken and the specified image is used instead. Currently it is not possible to limit the search scope to a portion of an Image object; please use the Image.copy() to cut the relevant section. Since the Image object specified as the search region cannot possibly change overtime, this function will not perform the image search repetitively and will return the results immediately.

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) )

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] )

# Find icon.png on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds )

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

// Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

// Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

// Find icon.png on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

// Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names::MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, ( waitForObject( names::MyWidget ),
                               waitForObject( names::MyOtherWidget ) ) );

# Find icon.png on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

# Find icon.png on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage "icon.png" {} [ waitForObject $names::MyWidget ]

# Find icon.png on multiple objects
waitForImage "icon.png" {} { [ waitForObject $names::MyWidget ],
                             [ waitForObject $names::MyOtherWidget ] }

# Find icon.png on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
waitForImage "icon.png" {} $bounds

# Find icon.png in the specified area
waitForImage "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Find icon.png on all top-level objects
waitForImage "icon.png" {} "all"