test.ocrTextPresent-function

Boolean test.ocrTextPresent(text, [parameterMap], [searchRegion])

Boolean test.ocrTextNotPresent(text, [parameterMap], [searchRegion])

This function will perform optical character recognition on the display also showing the currently running application and search for the specific text within the result set. If the specified text is present, 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.

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

The OCR will be performed over all available screens making up the desktop. At least on Windows and X11-based systems. For OCR 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.

• interval - Minimal number of milliseconds to wait in between OCR search retries. The default is 1000 (1 second). The actual interval between separate OCR attempts is dependent on OCR engine performance, and may be significantly longer.
• timeout - Amount of time in milliseconds to search for the specified text before reporting that the text is not found. The default is 20000 (20 seconds).
• occurrence - The occurrence index. By default the first text match (with index 1) will be returned. Index values 2 and higher will select consecutive matches as far as available.
• language - The language hint for OCR engine. Use an empty string to use the OCR engine defaults. The default value is the value of testSettings.defaultOcrLanguage property.
• profiles - An array of OCR engine specific profile names. This parameter is used only with engines that support profiles.
• options - A map of engine-specific option names and values. These options are passed to the OCR engine after loading the specified profiles.
• scaleFactor - Image up-scale factor. The source image is upscaled by that factor before it is passed to the OCR engine. The default value is 3.5. It can be set to a lower value to improve the OCR performance in case the text is rendered with a large font.
• 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 'Hier klicken' German text is displayed at least twice
test.ocrTextPresent("Hier klicken", {"occurrence": 2, "language": "German"})

// Verify the 'Hier klicken' German text is displayed at least twice
test.ocrTextPresent("Hier klicken", {occurrence: 2, language: "German"});

# Verify the 'Hier klicken' German text is displayed at least twice
test::ocrTextPresent("Hier klicken", {"occurrence" => 2, "language" => "German"});

# Verify the 'Hier klicken' German text is displayed at least twice
Test.ocrTextPresent("Hier klicken", {"occurrence" => 2, "language" => "German"})

# Verify the 'Hier klicken' German text is displayed at least twice
test ocrTextPresent "Hier klicken" {occurrence 2 language "German"}

By default this function will repeatedly grab the screen content until the specified text 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.

In case a searchRegion is specified as the last argument, the OCR 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 OCR 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 OCR repetitively and will return the results immediately.

# Verify the 'Click me' text is displayed on the MyWidget object
test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget )

# Verify the 'Click me' text is displayed on multiple objects
test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] )

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.ocrTextPresent( "Click me", {}, bounds )

# Verify the 'Click me' text is displayed in the specified area
test.ocrTextPresent( "Click me", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Verify the 'Click me' text is displayed on all top-level objects
test.ocrTextPresent( "Click me", {}, "all" )

# Verify the 'Click me' text is displayed on the MyWidget object
test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget ) );

// Verify the 'Click me' text is displayed on multiple objects
test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] );

// Verify the 'Click me' text is displayed on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
test.ocrTextPresent( "Click me", {}, bounds );

// Verify the 'Click me' text is displayed in the specified area
test.ocrTextPresent( "Click me", {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Verify the 'Click me' text is displayed on all top-level objects
test.ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
test::ocrTextPresent( "Click me", {}, waitForObject( names::MyWidget ) );

# Verify the 'Click me' text is displayed on multiple objects
test::ocrTextPresent( "Click me", {}, ( waitForObject( names::MyWidget ),
                                              waitForObject( names::MyOtherWidget ) ) );

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
test::ocrTextPresent( "Click me", {}, bounds );

# Verify the 'Click me' text is displayed in the specified area
test::ocrTextPresent( "Click me", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Verify the 'Click me' text is displayed on all top-level objects
test::ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
Test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget ) );

# Verify the 'Click me' text is displayed on multiple objects
Test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] );

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
Test.ocrTextPresent( "Click me", {}, bounds );

# Verify the 'Click me' text is displayed in the specified area
Test.ocrTextPresent( "Click me", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Verify the 'Click me' text is displayed on all top-level objects
Test.ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
test ocrTextPresent "Click me" {} [ waitForObject $names::MyWidget ]

# Verify the 'Click me' text is displayed on multiple objects
test ocrTextPresent "Click me" {} { [ waitForObject $names::MyWidget ],
                                    [ waitForObject $names::MyOtherWidget ] }

# Verify the 'Click me' text 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 ocrTextPresent "Click me" {} $bounds

# Verify the 'Click me' text is displayed in the specified area
test ocrTextPresent "Click me" {} [ construct ScreenRectangle 100 100 200 300 ]

# Verify the 'Click me' text is displayed on all top-level objects
test ocrTextPresent "Click me" {} "all"