Wait for Text to Appear on Screen

Applies to TestComplete 15.69, last modified on November 13, 2024

When testing your application, you may need to delay the test run until the expected text appears on screen:

  1. Use the OCR.Recognize.FullText property to capture the text rendered in a screen area.

  2. Check whether the captured text contains the expected text fragment. For example, you can use the aqString.Find method or any other string comparison method you find suitable. See Working With Strings.

  3. Repeat steps 1 and 2 in a loop until the expected text appears.

Notes:

  • Text recognition and string comparison in a loop may decrease your test performance. To avoid possible issues, you can add a delay to the loop.

  • To avoid an infinite loop, you can add conditions for exiting the loop earlier.

In scripts

The code below contains the CheckTextContents routine that gets an onscreen object and a string and verifies that the object’s text includes the string. As the third parameter, the routine takes a Boolean value that specifies whether the check is case-sensitive or case-insensitive. To get the onscreen object’s text, the routine uses the OCR.Recognize.FullText property. To verify that the text contains the string, the routine uses the aqString.Find method. If the string is present, the routine returns True; otherwise, it returns False.

The WaitForText routine in the sample code below calls the CheckTextContents routine in a loop until the CheckTextContents routine returns True, that is, until the tested application renders the expected text:

JavaScript, JScript

function CheckTextContents(anObject, aSubstring, caseSensitive)
{
  // Recognize the text contents of the specified onscreen object
  var text = OCR.Recognize(anObject).FullText;
  // Search for the occurrence of the specified substring in the recognized text
  return (aqString.Find(text, aSubstring, 0, caseSensitive) > -1)
}

function WaitForText()
{
  var textToWait = "substring";
  // Get the onscreen object whose text will be checked
  var obj = Sys.WaitProcess("MyApp").WaitWindow("Window", "*", -1, 3000);
  // Delay the test execution until the onscreen object text includes the expected substring
  while (! CheckTextContents(obj, textToWait, false))
    Delay(3000);

  // The onscreen object contains the needed text
  // Simulate user actions
  …
}

Python

def CheckTextContents(anObject, aSubstring, caseSensitive=False):
  # Recognize the text contents of the specified onscreen object
  text = OCR.Recognize(anObject).FullText
  # Search for the occurrence of the specified substring in the recognized text
  return (aqString.Find(text, aSubstring, 0 , caseSensitive) > -1)

def WaitForText():
  textToWait = "substring"
  # Get the onscreen object whose text will be checked
  obj = Sys.WaitProcess("MyApp").WaitWindow("Window", "*", -1, 3000)
  # Delay the test execution until the onscreen object text includes the expected substring
  while not CheckTextContents(obj, textToWait, False):
    Delay(3000)
  
  # The onscreen object contains the needed text
  # Simulate user actions
  # ...

VBScript

Function CheckTextContents(anObject, aSubstring, caseSensitive)
  ' Recognize the text contents of the specified onscreen object
  text = OCR.Recognize(anObject).FullText
  ' Search for the occurrence of the specified substring in the recognized text
  CheckTextContents = (aqString.Find(text, aSubstring, 0 , caseSensitive) > -1)
End Function

Sub WaitForText
  textToWait = "substring"
  ' Get the onscreen object whose text will be checked
  Set obj = Sys.WaitProcess("MyApp").WaitWindow("WindowClass", "*", -1, 3000)
  ' Delay the test execution until the onscreen object text includes the expected substring
  While Not CheckTextContents(obj, textToWait, False)
    Delay(3000)
  Wend

  ' The onscreen object contains the needed text
  ' Simulate user actions
  …
End Sub

DelphiScript

function CheckTextContents(anObject : OleVariant, aSubstring : String, caseSensitive : boolean = false);
var text;
begin
  // Recognize the text contents of the specified onscreen object
  text := OCR.Recognize(anObject).FullText;
  // Search for the occurrence of the specified substring in the recognized text
  result : = (aqString.Find(text, aSubstring, 0, caseSensitive) > -1);
end;

procedure WaitForText();
var obj, textToWait;
begin
  textToWait := 'substring';
  // Get the onscreen object whose text will be checked
  obj := Sys.WaitProcess('MyApp').WaitWindow('Window', '*', -1, 3000);
  // Delay the test execution until the onscreen object text includes the expected substring
  while not CheckTextContents(obj, textToWait, false) do
    Delay(3000);

  // The onscreen object contains the needed text
  // Simulate user actions
  …
end;

C++Script, C#Script

function CheckTextContents(anObject, aSubstring, caseSensitive)
{
  // Recognize the text contents of the specified onscreen object
  var text = OCR["Recognize"](anObject)["FullText"];
  // Search for the occurrence of the specified substring in the recognized text
  return (aqString["Find"](text, aSubstring, 0, caseSensitive) > -1);
}

function WaitForText()
{
  var textToWait = "substring";
  // Get the onscreen object whose text will be checked
  var obj = Sys["WaitProcess"]("MyApp")["WaitWindow"]("Window", "*", -1, 3000);
  // Delay the test execution until the onscreen object text includes the expected substring
  while (! CheckTextContents(obj, textToWait, false))
    Delay(3000);

  // The onscreen object contains the needed text
  // Simulate user actions
  …
}

In keyword tests

  1. Copy the CheckTextContents function code from the example above to a script unit in your test project in TestComplete.

  2. In your keyword test, call the CheckTextContents function in a loop until the function returns True.

    To call the routine, you can use the Run Code Snippet or the Run Script Routine operation. To create a loop in a keyword test, use the While Loop operation.

Delay the test run until the expected substring appears on the screen

See Also

Optical Character Recognition
Delaying Test Execution
Organizing Loops

Highlight search results