test.imagePresent

Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion])

This function will perform a search of the template image as stored in imageFile on the display also showing the currently running application. On success a test result of type PASS is added to the test log and the function returns true. Otherwise a test result of type FAIL is added to the test log and the function returns false.

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

Boolean test.imageNotPresent(imageFile, [parameterMap], [searchRegion])

The imageNotPresent() variant of the function works exactly the same as imagePresent(), except it waits for the image NOT to be found. It can be used to verify the image absence.

The search for the sub-image is performed left to right, top to bottom. The first successful match is selected. For selection of other matches use the occurrence parameter as described below.

All available screens making up the desktop will be searched. At least on Windows and X11-based systems. For searches on multi-screen setup on macOS please inquire with technical support.

The search behavior can be configured through entries passed via the optional parameterMap argument.

• 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).

# Verify the icon.png is displayed
test.imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
test.imagePresent("icon.png", {"occurrence": 2})

// Verify the icon.png is displayed
test.imagePresent("icon.png");
// Verify the icon.png is displayed at least twice
test.imagePresent("icon.png", {"occurrence": 2});

# Verify the icon.png is displayed
test::imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
test::imagePresent("icon.png", {"occurrence" => 2})

# Verify the icon.png is displayed
Test.imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
Test.imagePresent("icon.png", {"occurrence" => 2})

# Verify the icon.png is displayed
test imagePresent "icon.png"
# Verify the icon.png is displayed at least twice
test imagePresent "icon.png" {"occurrence": 2}

By default this function will repeatedly grab the screen content until an image is found or until 20 seconds have passed. Longer (or shorter) waiting periods can be set in milliseconds via a timeout value passed through the parameterMap.

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.

# Verify the icon.png is displayed
test.imagePresent( "icon.png", {'tolerant': True,
                                'threshold': 99.7,
                                'multiscale': True,
                                'minScale': 100.0,
                                'maxScale': 150.0})

// Verify the icon.png is displayed
test.imagePresent("icon.png", {tolerant: true,
                               threshold: 99.7,
                               multiscale: true,
                               minScale: 100.0,
                               maxScale: 150.0});

# Verify the icon.png is displayed
test::imagePresent("icon.png", {tolerant => true,
                                threshold => 99.7,
                                multiscale => true,
                                minScale => 100.0,
                                maxScale => 150.0}) );

# Verify the icon.png is displayed
Test.imagePresent("icon.png", {"tolerant" => true,
                               "threshold" => 99.7,
                               "multiscale" => true,
                               "minScale" => 100.0,
                               "maxScale" => 150.0}) )

# Verify the icon.png is displayed
test imagePresent "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 result immediately.

# Verify the icon.png is displayed on the MyWidget object
test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) )

# Verify the icon.png is displayed on multiple objects
test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] )

# Verify the icon.png is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.imagePresent("icon.png", {}, bounds )

# Verify the icon.png is displayed in the specified area
test.imagePresent("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Verify the icon.png is displayed on all top-level objects
test.imagePresent("icon.png", {}, "all" )

// Verify the icon.png is displayed on the MyWidget object
test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) );

// Verify the icon.png is displayed on multiple objects
test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

// Verify the icon.png is displayed on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
test.imagePresent("icon.png", {}, bounds );

// Verify the icon.png is displayed in the specified area
test.imagePresent("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Verify the icon.png is displayed on all top-level objects
test.imagePresent("icon.png", {}, "all" );

# Verify the icon.png is displayed on the MyWidget object
test::imagePresent("icon.png", {}, waitForObject( names::MyWidget ) );

# Verify the icon.png is displayed on multiple objects
test::imagePresent("icon.png", {}, ( waitForObject( names::MyWidget ),
                            waitForObject( names::MyOtherWidget ) ) );

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

# Verify the icon.png is displayed in the specified area
test::imagePresent("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Verify the icon.png is displayed on all top-level objects
test::imagePresent("icon.png", {}, "all" )

# Verify the icon.png is displayed on the MyWidget object
Test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) );

# Verify the icon.png is displayed on multiple objects
Test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

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

# Verify the icon.png is displayed in the specified area
Test.imagePresent("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Verify the icon.png is displayed on all top-level objects
Test.imagePresent("icon.png", {}, "all" );

# Verify the icon.png is displayed on the MyWidget object
test imagePresent "icon.png" {} [ waitForObject $names::MyWidget ]

# Verify the icon.png is displayed on multiple objects
test imagePresent "icon.png" {} { [ waitForObject $names::MyWidget ],
                                   [ waitForObject $names::MyOtherWidget ] }

# Verify the icon.png is displayed 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 ]
test imagePresent "icon.png" {} $bounds

# Verify the icon.png is displayed in the specified area
test imagePresent "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Verify the icon.png is displayed on all top-level objects
test imagePresent "icon.png" {} "all"