Waiting for Object State Changes

Applies to TestComplete 14.72, last modified on April 22, 2021

When testing an application, it can be necessary to wait for a specific application response. For example, changes in the state of a control (enabled/disabled) or changes in a specific screen region. A loop can test the condition until it becomes true. But this would seriously slow the execution of the application, as TestComplete would be continuously testing. So, make sure that you insert a delay command, that can be:

  • In keyword tests - the Delay operation with specified Delay Time parameter.

  • In scripts - a call to aqUtils.Delay within the loop body.

To check whether a control is enabled, use the Enabled property of onscreen objects. Note, that you can get this property both from keyword tests and scripts. To get the property from a keyword test, do the following:

The following code shows how to implement a delay from a script (script execution waits until the OK button becomes enabled). In this routine the delay is organized in a loop.

Note: You can also add loops to keyword tests, see While Loop Operation or For Loop Operation.

JavaScript, JScript

btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2);
while(! btn.Enabled)
  aqUtils.Delay(1000); // 1 sec delay

Python

btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2)
while not btn.Enabled:
  aqUtils.Delay(1000) # 1 sec delay

VBScript

Set btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2)
While Not btn.Enabled
  aqUtils.Delay 1000 ' 1 sec delay
WEnd

DelphiScript

btn := Sys.Process('MyApp').Window('TMainFrm','MyApplication *').Child(2);
while not btn.Enabled do
  aqUtils.Delay(1000); // 1 sec delay

C++Script, C#Script

btn = Sys["Process"]("MyApp")["Window"]("TMainFrm", "MyApplication *")["Child"](2);
while(! Btn["Enabled"])
  aqUtils["Delay"](1000); // 1 sec delay

An alternative to checking the Enabled property in a loop is to use the object’s WaitProperty method. It lets you pause the test execution until the specified object property becomes equal to the specified value, or until the specified timeout is over. The following code demonstrates the use of this method:

JavaScript, JScript

var btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2);
if (btn.WaitProperty("Enabled", true, 2000))
  // Button is enabled
else
  // Button is disabled

Python

btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2)
if btn.WaitProperty("Enabled", True, 2000):
   # Button is enabled
else:
   # Button is disabled

VBScript

Set btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2)
If btn.WaitProperty("Enabled", True, 2000) Then
  ' Button is enabled
Else
  ' Button is disabled
End If

DelphiScript

var
  btn : OleVariant;
begin
  btn := Sys.Process('MyApp').Window('TMainFrm','MyApplication *').Child(2);
  if btn.WaitProperty('Enabled', true, 2000) then
    // Button is enabled
  else
    // Button is disabled
end;

C++Script, C#Script

var btn = Sys["Process"]("MyApp")["Window"]("TMainFrm","MyApplication *")["Child"](2);
if (btn["WaitProperty"]("Enabled", true, 2000))
  // Button is enabled
else
  // Button is disabled

The benefit of the WaitProperty method is that it is more compact than the loop statement and it lets you easily limit the ”waiting“ time. However, the loop approach lets you detect changes in several object properties, while WaitProperty work for one property only.

To check whether a specific screen region is changed, use the Regions.Compare method. It compares two images and returns True if they are equal (see About Region Checkpoints).

The following example delays test execution until a specified screen region changes:

JavaScript, JScript

w = Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50);
while (w.Compare(Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)))
  aqUtils.Delay(500); // 0.5 sec delay

Python

w = Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)
while w.Compare(Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)):
   aqUtils.Delay(500) # 0.5 sec delay

VBScript

Set w = Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)
While w.Compare(Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50))
  aqUtils.Delay 500 ' 0.5 sec delay
Wend

DelphiScript

// Obtains a screen region
w := Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50);
while w.Compare(Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)) do
  aqUtils.Delay(500); // 0.5 sec delay

C++Script, C#Script

w = Sys["Desktop"]["ActiveWindow"]()["Picture"](20, 20, 50, 50);
while (w["Compare"](Sys["Desktop"]["ActiveWindow"]()["Picture"](20, 20, 50, 50)))
  aqUtils["Delay"](500); // 0.5 sec delay

See Also

Working With Application Objects and Controls
Common Tasks
Delaying Test Execution
Compare Method
WaitProperty Method
Waiting for an Object, Process or Window Activation
Waiting for an Object to Have a Specific Property Value

Highlight search results