Waiting for an Object to Have a Specific Property Value

Applies to TestComplete 15.63, last modified on April 23, 2024

In your automated tests, you may need to wait until a tested object gets an expected property value. This may be useful if an expected event occurs in your tested application only after a tested object goes into a particular state. For example, in a dialog showing some operation progress, the OK button becomes enabled only after the progress bar reaches 100%.

To wait for an object to have a specific property value, you use the WaitProperty method. The parameters of this method specify:

  • Property name.

  • Expected value.

  • Timeout (optional). If a timeout is provided, the method waits for the property to have the expected value until the timeout elapses; otherwise, it checks the property value only once.

The method returns True if the expected property value has been reached and False otherwise.

The method does not post the check result to the test log; however, you can get the method’s return value, check it using the if … then statement, and control the further test run according to the check result.

The WaitProperty method can also be used for property checkpoints, to verify that a particular property value is reached within a timeout (as built-in property checkpoints do not support timeouts).

In keyword tests

To call the WaitProperty method, you can use the On-Screen Action operation or the Call Object Method operation. For example:

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

  2. In the resulting wizard, configure the operation to call the WaitProperty method:

    1. Specify the object whose property value you want to wait for. You can type the object name manually, or you can select the object onscreen.

      Note: The object must exist in the system.

    2. In the object members list, select WaitProperty and click Next.

    3. Specify the name of the property and its expected value.

    4. If needed, set the timeout, in milliseconds.

    5. Click Finish.

  3. To check the method result, use the If … Then operation. Add it right after the WaitProperty method call.

  4. To specify operations to run if the property value has been reached, add them as child items of the If … Then operation.

  5. To specify an operation to run if the property value has not been reached, add the Else operation right after the If … Then operation, and then add the needed operations as child items of the Else operation.

Desktop
Web (Cross-platform)

Desktop

Waiting for a property value in a keyword test

Click the image to enlarge it.

Web (Cross-Platform)

Waiting for a property value in a keyword test

Click the image to enlarge it.

In script tests

The following code shows how to use the WaitProperty method to wait for a property to take an expected value:

Desktop
Web (Cross-platform)

Desktop

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var btn = Sys.Process("SampleApp").Window("TForm", "Progress").Window("Button", "OK");
  if (btn.WaitProperty("Enabled", true, 15000))
  {
    btn.ClickButton();
  }
  else
  {
    Log.Error("The OK button didn't become enabled within 15 seconds.");
  }
}

Python

def Test():
  btn = Sys.Process("SampleApp").Window("TForm", "Progress").Window("Button", "OK")
  if (btn.WaitProperty("Enabled", True, 15000)):
    btn.ClickButton();
  else:
    Log.Error("The OK button didn't become enabled within 15 seconds.")

VBScript

Sub Test()
  Set btn = Sys.Process("SampleApp").Window("TForm", "Progress").Window("Button", "OK")
  If btn.WaitProperty("Enabled", true, 15000) Then
    btn.ClickButton
  Else
    Log.Error("The OK button didn't become enabled within 15 seconds.")
  End If
End Sub

DelphiScript

procedure Test();
var btn;
begin  btn := Sys.Process('SampleApp').Window('TForm', 'Progress').Window('Button', 'OK');
  if btn.WaitProperty('Enabled', true, 15000) then
    btn.ClickButton
  else
    Log.Error('The OK button didn''t become enabled within 15 seconds.');
end;

C++Script, C#Script

function Test()
{
  var btn = Sys["Process"]("SampleApp")["Window"]("TForm", "Progress")["Window"]("Button", "OK");
  if (btn["WaitProperty"]("Enabled", true, 15000))
  {
    btn["ClickButton"]();
  }
  else
  {
    Log["Error"]("The OK button didn't become enabled within 15 seconds.");
  }
}

Web (Cross-Platform)

JavaScript, JScript
Python
VBScript
DelphiScript
C++Script, C#Script
Copy Code

JavaScript, JScript

function Test()
{
  var url = "https://www.w3schools.com/cssref/tryit.asp?filename=trycss3_transition-delay";
  var expectedWidth = 300;
  var timeout = 7000;

  Browsers.Item(btChrome).Run(url);
  var div = Sys.Browser().Page(url).FindElement("#iframeResult").FindElement("div");

  div.HoverMouse();

  if (div.WaitProperty("Width", expectedWidth, timeout))
  {
    Log.Message("The element's width property has reached the expected value.");
  }
  else
  {
    Log.Warning("The element's width property hasn't reached the expected value.");
  }
}

Python

def Test():
  url = "https://www.w3schools.com/cssref/tryit.asp?filename=trycss3_transition-delay"
  expectedWidth = 300
  timeout = 7000
  
  Browsers.Item[btChrome].Run(url)
  div = Sys.Browser().Page(url).FindElement("#iframeResult").FindElement("div")
  
  div.HoverMouse()
  
  if (div.WaitProperty("Width", expectedWidth, timeout)):
    Log.Message("The element's width property has reached the expected value.")
  else:
    Log.Warning("The element's width property hasn't reached the expected value.")

VBScript

Sub Test()
  url = "https://www.w3schools.com/cssref/tryit.asp?filename=trycss3_transition-delay"
  expectedWidth = 300
  timeout = 7000

  Browsers.Item(btChrome).Run(url)
  Set div = Sys.Browser().Page(url).FindElement("#iframeResult").FindElement("div")

  div.HoverMouse

  If div.WaitProperty("Width", expectedWidth, timeout) Then
    Log.Message("The element's width property has reached the expected value.")
  Else
    Log.Warning("The element's width property hasn't reached the expected value.")
  End If

End Sub

DelphiScript

procedure Test();
var url, expectedWidth, timeout, panel;
begin
  url := 'https://www.w3schools.com/cssref/tryit.asp?filename=trycss3_transition-delay';
  expectedWidth := 300;
  timeout := 7000;

  Browsers.Item[btChrome].Run(url);
  panel := Sys.Browser().Page(url).FindElement('#iframeResult').FindElement('div');

  panel.HoverMouse;

  if panel.WaitProperty('Width', expectedWidth, timeout) then
    Log.Message('The element''s width property has reached the expected value.')
  else
    Log.Warning('The element''s width property hasn''t reached the expected value.');

end;

C++Script, C#Script

function Test()
{
  var url = "https://www.w3schools.com/cssref/tryit.asp?filename=trycss3_transition-delay";
  var expectedWidth = 300;
  var timeout = 7000;

  Browsers["Item"](btChrome).Run(url);
  var div = Sys["Browser"]()["Page"](url)["FindElement"]("#iframeResult")["FindElement"]("div");

  div["HoverMouse"]();

  if (div["WaitProperty"]("Width", expectedWidth, timeout))
  {
    Log["Message"]("The element's width property has reached the expected value.");
  }
  else
  {
    Log["Warning"]("The element's width property hasn't reached the expected value.");
  }
}

Remarks

The WaitProperty method has a few limitations:

  • It does not support indexed properties, that is, properties that take parameters (for example, wItem(5)). To wait for the value of an indexed property, use a loop statement. See Waiting for Object State Changes for examples.

  • It only supports waiting for a single property value; it does not support checking multiple properties.

See Also

Common Tasks
WaitProperty Method
Waiting for Object State Changes
Delaying Test Execution

Highlight search results