Waiting for an Object to Have a Specific Property Value

Applies to TestComplete 15.20, last modified on January 19, 2022

When creating automated tests, you may need to synchronize the test run based on an object property value. This is useful if an event occurs in your tested application (say, objects are displayed or become enabled) only after a certain object goes into a particular state. For example, the OK button in a dialog indicating the progress of some operation becomes enabled only after the progress bar reaches 100%, or some additional options become available after specific text is displayed in a window. In these and similar cases, you need to instruct TestComplete to wait until an object has the required property value before continuing the test run.

To wait for an object to have a specific property value, you use the WaitProperty method. The parameters of this method specify the property name, expected value, and (optionally) timeout. If a timeout is provided, the method checks for the specified property value until the timeout elapses, otherwise, it checks for it only once. The result of the check is not reported to the test log, but it is available through the method’s return value: True if the specified property value has been reached and False otherwise. You can examine this return value using the if … then statement and control the further test run according to the result of the check.

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

Waiting for a Property Value in Keyword Tests

To add the WaitProperty method call to a keyword test, use the On-Screen Object operation. Below are the instructions to configure this operation:

  • Add the On-Screen Action operation to your keyword test. The Operation Parameters wizard will open.

  • Specify the object whose property value you want to wait for and press Next.

  • In the object members list, select WaitProperty and press Next.

  • Specify a parameter value for the WaitProperty method:

    • PropertyName - the name of the property to wait for;

    • PropertyValue - the property value to wait for;

    • WaitTime - the timeout, in milliseconds (for example, 15000 means 15 seconds).

  • Once you are done, press Finish.

To check the WaitProperty method result, use the If ... Then operation:

  • Add the If ... Then operation to your keyword test after the WaitProperty method call. The Operation Parameters dialog will open.

  • Click the ellipsis button in the Value1 column.

  • In the Edit Value dialog, select Last Operation Result from the Mode drop-down list and press OK.

  • Click the ellipsis button in the Value2 column.

  • In the Edit Value dialog, select the values below and press OK:

    • Mode: Constant
    • Type: Boolean
    • Value: True

  • Press OK to close the Operation Parameters dialog.

To specify the operations to execute if the property value has been reached:

  • Add the needed operations as child items of the If ... Then operation.

To specify the operations to execute if the property value has not been reached:

  • Add the Else operation right after the If ... Then operation.

  • Add the needed operations as child items of the Else operation.

The image below demonstrates a sample keyword test that uses the WaitProperty method. This test waits for a button to become enabled for 15 seconds. If the button becomes enabled, TestComplete clicks on it, otherwise, it posts an error to the test log:

A keyword testing using the WaitProperty method

Waiting for a Property Value in Scripts

The following code is an example of using the WaitProperty method in scripts. It is similar to the keyword test above, and waits for a button to become enabled for 15 seconds:

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

JavaScript, JScript

if (Aliases.SampleApp.btnOK.WaitProperty("Enabled", true, 15000))
{
  Aliases.SampleApp.btnOK.ClickButton();
}
else
{
  Log.Error("The OK button didn't become enabled within 15 seconds.");
}

Python

if Aliases.SampleApp.btnOK.WaitProperty("Enabled", True, 15000):
   Aliases.SampleApp.btnOK.ClickButton
else:
   Log.Error("The OK button didn't become enabled within 15 seconds.")

VBScript

If Aliases.SampleApp.btnOK.WaitProperty("Enabled", True, 15000) Then
  Aliases.SampleApp.btnOK.ClickButton
Else
  Log.Error "The OK button didn't become enabled within 15 seconds."
End If

DelphiScript

if Aliases.SampleApp.btnOK.WaitProperty('Enabled', true, 15000) then
  Aliases.SampleApp.btnOK.ClickButton
else
  Log.Error('The OK button didn''t become enabled within 15 seconds.');

C++Script, C#Script

if (Aliases["SampleApp"]["btnOK"]["WaitProperty"]("Enabled", true, 15000))
{
  Aliases["SampleApp"]["btnOK"]["ClickButton"]();
}
else
{
  Log["Error"]("The OK button didn't become enabled within 15 seconds.");
}

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, you need to 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