Waiting for Object State Changes

Applies to TestComplete 15.40, last modified on March 25, 2022

In your test, you may need to wait for an application response. For example, you may need to wait until the control state changes (enabled or disabled) or wait for changes in a screen region. You can do it in several ways.

Check object properties in a loop

A loop can test conditions until they become true. In a keyword test, you implement a loop with the While Loop operation or the For Loop operation. In script tests, you use the for or while statements.

For example, to make a keyword test wait until a tested object is visible on screen:

  1. Add a loop operation, for example, the While Loop operation, to your keyword test.

  2. Specify the condition that will check that the object’s property has the expected value:

    • In the Value 1 column, click the ellipsis button.

    • In the resulting Edit Value dialog, set the mode to Object Property, and in the Value text box, specify the object property to check. You can type the property manually, or you can click the ellipsis button, select the object onscreen, and then select its property. The object must exist in the system.

      In our example, we select the VisibleOnScreen property.

    • In the Condition column, specify the condition that will validate the specified object’s property. In our example, we select Does not equal.

    • In the Value 2 column, click the ellipsis button and set the baseline value against which you want to validate the object’s property. In our case, we set the baseline value to False, so that our loop will go until the object’s VisibleOnScreen property turns True.

Desktop

Using a loop to wait until the object changes its state

Click the image to enlarge it.

Web (Cross-Platform)

Using a loop to wait until the object changes its state

Click the image to enlarge it.

The script example below shows how to make a test to wait for an object to become visible on screen:

Desktop

JavaScript, JScript

btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication*").Child(2);
while(! btn.VisibleOnScreen) {}

Python

btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication *").Child(2)
while not btn.VisibleOnScreen:
  pass

VBScript

Set btn = Sys.Process("MyApp").Window("TMainFrm","MyApplication*").Child(2)
While Not btn.VisibleOnScreen
WEnd

DelphiScript

btn := Sys.Process('MyApp').Window('TMainFrm','MyApplication *').Child(2);
while not btn.VisibleOnScreen do
  begin end;

C++Script, C#Script

btn = Sys["Process"]("MyApp")["Window"]("TMainFrm","MyApplication *")["Child"](2);
while(! Btn["VisibleOnScreen"]) {}

Web (Cross-Platform)

JavaScript, JScript

Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/");
var txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']");
while (txtWelcome.VisibleOnScreen != true) {}

Python

Browsers.Item[btChrome].Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
while (txtWelcome.VisibleOnScreen != True):
  pass

VBScript

Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
Set txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
While (txtWelcome.VisibleOnScreen <> True)
WEnd

DelphiScript

var txtWelcome;

begin
Browsers.Item(btChrome).Run('https://services.smartbear.com/samples/TestComplete14/smartstore/');
txtWelcome := Sys.Browser().Page('*').FindElement('//h1[.="Welcome to our store"]');
while txtWelcome.VisibleOnScreen <> true do
  begin end;

end;

C++Script, C#Script

Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/");
var txtWelcome = Sys["Browser"]()["Page"]("*")["FindElement"]("//h1[.='Welcome to our store']");
while (txtWelcome["VisibleOnScreen"] != true) {}

Note, however, that using loops this way can slow down both the test’s performance and the performance of the application under test as the test engine will be constantly getting the object, retrieving its properties, and checking the condition. If you use the loop, make sure to add a delay command into it:

  • In keyword tests, use the Delay operation:

    Desktop

    Using a loop with delay

    Click the image to enlarge it.

    Web (Cross-Platform)

    Using a loop with delay

    Click the image to enlarge it.

  • In scripts, use the Delay method:

    Desktop

    JavaScript, JScript

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

    Python

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

    VBScript

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

    DelphiScript

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

    C++Script, C#Script

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

    Web (Cross-Platform)

    JavaScript, JScript

    Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/");
    var txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']");
    while (txtWelcome.VisibleOnScreen != true)
      Delay(1000); // 1 sec delay

    Python

    Browsers.Item[btChrome].Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
    txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
    while (txtWelcome.VisibleOnScreen != True):
      Delay(1000) # 1 sec delay

    VBScript

    Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
    Set txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
    While (txtWelcome.VisibleOnScreen <> True)
      Delay(1000) ' 1 sec delay
    WEnd

    DelphiScript

    var txtWelcome;

    begin
    Browsers.Item(btChrome).Run('https://services.smartbear.com/samples/TestComplete14/smartstore/');
    txtWelcome := Sys.Browser().Page('*').FindElement('//h1[.="Welcome to our store"]');
    while txtWelcome.VisibleOnScreen <> true do
      Delay(1000); // 1 sec delay

    end;

    C++Script, C#Script

    Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/");
    var txtWelcome = Sys["Browser"]()["Page"]("*")["FindElement"]("//h1[.='Welcome to our store']");
    while (txtWelcome["VisibleOnScreen"] != true)
      Delay(1000); // 1 sec delay

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

Use the WaitProperty method

Another way to wait for a tested object to change its state is to use the WaitProperty method. It pauses the test run until the specified property equals the expected value or until the specified timeout expires. To check if the property gets the expected value, check if the WaitProperty method result is True.

Desktop

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

Web (Cross-Platform)

JavaScript, JScript

Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/");
var txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']");
if (txtWelcome.WaitProperty("VisibleOnScreen", "true", 2000))
{
  // Element is visible
  // ...
}
else
{
  // Element is not visible
  // ...
}

Python

Browsers.Item[btChrome].Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
if (txtWelcome.WaitProperty("VisibleOnScreen", True, 2000)):
  # Element is visible
  pass
  # ...
else:
  # Element is not visible
  pass
  # ...

VBScript

Browsers.Item(btChrome).Run("https://services.smartbear.com/samples/TestComplete14/smartstore/")
Set txtWelcome = Sys.Browser().Page("*").FindElement("//h1[.='Welcome to our store']")
If txtWelcome.WaitProperty("VisibleOnScreen", "true", 2000) Then
  ' Element is visible
  ' ...
Else
  ' Element is not visible
  ' ...
End If

DelphiScript

var txtWelcome;

begin
Browsers.Item(btChrome).Run('https://services.smartbear.com/samples/TestComplete14/smartstore/');
txtWelcome := Sys.Browser().Page('*').FindElement('//h1[.="Welcome to our store"]');
if txtWelcome.WaitProperty('VisibleOnScreen', 'true', 2000) then
begin
  // Element is visible
  // ...
end
else
begin
  // Element is not visible
  // ...
end;

C++Script, C#Script

Browsers["Item"](btChrome)["Run"]("https://services.smartbear.com/samples/TestComplete14/smartstore/");
var txtWelcome = Sys["Browser"]()["Page"]("*")["FindElement"]("//h1[.='Welcome to our store']");
if (txtWelcome["WaitProperty"]("VisibleOnScreen", "true", 2000))
{
  // Element is visible
  // ...
}
else
{
  // Element is not visible
  // ...
}

To call the method in keyword tests, use the Call Object Method operation:

  1. Add the Call Object Method operation to your keyword test.

  2. Specify the object whose state you want to check. You can type the object name manually or you can select the object onscreen.

  3. Select the WaitProperty method of the object and specify the property to check, the expected value, and a timeout.

  4. To check the WaitProperty method result, you can use the If…Then operation. Add the operation to your test right after the Call Object Method operation.

  5. Configure the operation to compare the Last operation result to a boolean value.

Desktop

Using the WaitProperty method

Click the image to enlarge it.

Web (Cross-Platform)

Using the WaitProperty method

Click the image to enlarge it.

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 works for one property only.

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