Applies to TestComplete 14.20, last modified on September 11, 2019
In version 12.60, the Optical Character Recognition feature was upgraded to a new plugin powered by Google Cloud Vision API. To learn more, see Optical Character Recognition.
The deprecated OCR plugin was removed from TestComplete in version 12.60. If you need to use the deprecated OCR plugin with this version of TestComplete, please contact our Customer Care team. The deprecated OCR plugin was restored in TestComplete version 14.0. To use the plugin with this or later TestComplete version, you need to install and enable the plugin manually.

The TestComplete OCR engine uses specific algorithms to “read” text from an onscreen region character by character. These algorithms depend on several factors: font, text and background colors, text size and others. All of these factors make optical recognition prone to errors. TestComplete includes the Text Recognition plugin that uses other principles for text recognition. The plugin intercepts calls to certain Windows API functions that output text on screen and tries to create special test objects for this text. This plugin works faster than the OCR engine and, if used, provides 100% recognition accuracy.

This topic describes how you can use the Text Recognition plugin to perform the actions which the OCR engine performs and explains when you use this or that technology.

Typical OCR Tasks

Typically, testers use the TestComplete OCR subsystem when they cannot obtain text from an object for some reason or when they needed to find a test object that contains text. Let’s consider these typical tasks in detail:

  • Finding an object by text

    Suppose you are testing an application that uses a third-party menu system which is not supported by TestComplete. Since the menu is not supported, TestComplete will not provide methods and objects for simulating user actions over the menu.

    To work around the problem, you can simulate selecting the menu item by calling the Click method of the tested form and passing the coordinates of desired items to this method as parameters. However, it is difficult to create and maintain such tests. Also, hard-coded coordinates will make the test less stable: if the position of the desired menu item changes, the test will fail.

    The OCR subsystem offers a better solution. It helps you find the rectangular area of screen that contains the desired text. After you get the area, you can pass the desired coordinates to the Click method and simulate the desired action.

    The Text Recognition plugin also helps you solve this problem. It recognizes menu items by their text and creates the TextObject object for each item. You can easily simulate selecting an item by calling the Click method of the TextObject object.

  • Getting text of an object

    Let’s consider another example: a tested form contains a label and your test should simulate a click over it. This task is not a problem if you are testing an Open Application. However, it may become a problem if you have to test a black-box application. It is quite possible that the tested application does not create a special window to display the label’s text, but draws the text on the surface of the tested form. The TestComplete object hierarchy will not contain an object that corresponds to this label, so it may be difficult to determine the label’s text and compare it with some baseline value.

    Using the OCR engine you can recognize this text and perform the desired comparison. The Text Recognition plugin also helps you solve this problem. See below for more information.

Finding an Object by Text

To find the coordinates of text on screen, you can use the FindRectByText method of an OCRObject object. This method recognizes the whole text within some visual region and then searches for the rectangle that surrounds the desired text.

As an alternative to the FindRectByText method, you can use the Text Recognition plugin:

  • Enable the Text Recognition support for your tested form or controls in TestComplete project properties. For more information about this, see the description of the Text Recognition subsystem.

    After this, TestComplete will use the Text Recognition engine to recognize text drawn in your tested application and will create TextObject objects for them.

  • If you know the text the desired control contains, then after you enable the Text Recognition support, you can use code like TextObject("My Text") to obtain the object holding the desired text. For instance:

    JavaScript, JScript

    var myWnd, textObj;
     
    // Get the tested window
    myWnd = Sys.Process("MyProcess").Window("MyWindowClass", "My Window Caption", 1);
     
    // Get the TextObject object
    textObj = myWnd.TextObject("My Desired Text");

    Python

    # Get the tested window
    myWnd = Sys.Process("MyProcess").Window("MyWindowClass", "My Window Caption", 1)
     
    # Get the TextObject object
    textObj = myWnd.TextObject("My Desired Text")

    VBScript

    ' Get the tested window
    Set myWnd = Sys.Process("MyProcess").Window("MyWindowClass", "My Window Caption", 1)
     
    ' Get the TextObject object
    Set textObj = myWnd.TextObject("My Desired Text")

    DelphiScript

    var
      myWnd, textObj : OleVariant;
    begin
      // Get the tested window
      myWnd := Sys.Process('MyProcess').Window('MyWindowClass', 'My Window Caption', 1);
      
      // Get the TextObject object
      textObj := myWnd.TextObject('My Desired Text');
    end;

    C++Script, C#Script

    var myWnd, textObj;

    // Get the tested window
    myWnd = Sys["Process"]("MyProcess")["Window"]("MyWindowClass", "My Window Caption", 1);
     
    // Get the TextObject object
    textObj = myWnd["TextObject"]("My Desired Text");

    If you do not know the exact text, then you can enumerate child objects of the tested window and compare their names and text with the desired values.

    To enumerate child objects, you use the Child method and ChildCount property of the form. The names of the objects created by the Text Recognition plugin look like TextObject("desired text"). To obtain the text, use the Text property of TextObject objects.

    If the form contains several TextObject objects having similar text, then to find the needed object, you can check its Index property or check the properties that return the object's coordinates: Top, Left, ScreenTop and ScreenLeft.

    To find a child object by its property values, you can also use the Find and FindChild methods of the tested form.

After you obtain the text object, you can perform the needed actions with it. For instance, you can use the Click and ClickR methods to simulate mouse clicks over the object.

Getting Text of an Object

Another common task for the OCR engine is to obtain text of some control. To do this, you can use the OCR.CreateObject(...).GetText method. Alternatively, you can use Text Recognition services:

  • First, enable Text Recognition services in your project’s properties. For more information on this, see the description of the Text Recognition subsystem.

  • Your further actions depend on the application under test:

    • If you know the screen coordinates of some point within the text, you can pass them to the Sys.ObjectFromPoint or Sys.Desktop.ObjectFromPoint method and the method will return the TextObject object that provides a scripting interface to the desired text.

      You can find the coordinates in the Object Browser panel before running tests.

    • If the text coordinates may change from one test run to another, then you need to enumerate through child objects of the window that contains the desired text and check the properties of the child objects. For instance, you can use the Index property or the properties that return the coordinates of the text object: Top, Left, ScreenTop and ScreenLeft.

      To find a child object by its property values, you can also use the Find or FindChild method of the tested form.

When to Use OCR and When to Use Text Recognition

Since the Text Recognition plugin uses other principles to determine object text, it works faster than the OCR engine and, if used, provides 100% recognition accuracy. We recommend that you always use Text Recognition services to work with text controls. If Text Recognition does not help, then use OCR.

Note however that there are situations when the Text Recognition plugin will not be helpful:

  • A tested window displays an image that includes some text. Since this text is part of the image, the Text Recognition plugin will not be able to create a TextObject object for it. Such images are typically used by web pages. If you need to obtain text shown in an image, you have to use the OCR engine.

  • The way the tested application draws text is not typical for Windows applications. For instance, if the application draws text pixel by pixel rather than calls the DrawText function of Windows API, the Text Recognition plugin will not be able to determine the drawn text and will not create a TextObject object for it. To recognize such text, use the OCR engine.

See Also

Using Optical Character Recognition - Overview
Using Text Recognition Technology

Highlight search results