waitForOcrText

ScreenRectangle waitForOcrText(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. It will return a ScreenRectangle object corresponding to the location of the text.

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.

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence": 2, "language": "German"})

// Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {occurrence: 2, language: "German"}));

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence" => 2, "language" => "German"}));

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence" => 2, "language" => "German"}))

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
invoke mouseClick [waitForOcrText "Hier klicken" {occurrence 2 language "German"}]

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 OCR search, use the ScreenRectangle findOcrText(text, [parameterMap], [searchRegion]) function.

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence": 2, "timeout": 10000})

// Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {occurrence: 2, timeout: 10000}));

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence" => 2, "timeout" => 10000}));

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence" => 2, "timeout" => 10000}))

# Click on second 'Click me' occurrence, wait maximum 10 seconds
invoke mouseClick [waitForOcrText "Click me" {occurrence 2 timeout 10000}]

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.

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) )

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) )

# Click on text on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) )

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) )

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

// Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) );

// Click on text on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

// Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) );

// Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names::MyWidget ) ) );

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, ( waitForObject( names::MyWidget ),
                                              waitForObject( names::MyOtherWidget ) ) ) );

# Click on text on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) );

# Click on text on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
invoke mouseClick [ waitForOcrText "Click me" {} [ waitForObject $names::MyWidget ] ]

# Click on text on multiple objects
invoke mouseClick [ waitForOcrText "Click me" {} { [ waitForObject $names::MyWidget ],
                                                   [ waitForObject $names::MyOtherWidget ] } ]

# Click on text 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 ]
invoke mouseClick [ waitForOcrText "Click me" {} $bounds ]

# Click on text in the specified area
invoke mouseClick [ waitForOcrText "Click me" {} [ construct ScreenRectangle 100 100 200 300 ] ]

# Click on text on all top-level objects
invoke mouseClick [ waitForOcrText "Click me" {} "all" ]