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.
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).
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
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:
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:
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:
if (Aliases.SampleApp.btnOK.WaitProperty("Enabled", true, 15000))
Log.Error("The OK button didn't become enabled within 15 seconds.");
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.")
If Aliases.SampleApp.btnOK.WaitProperty("Enabled", True, 15000) Then
Log.Error "The OK button didn't become enabled within 15 seconds."
if Aliases.SampleApp.btnOK.WaitProperty('Enabled', true, 15000) then
Log.Error('The OK button didn''t become enabled within 15 seconds.');
if (Aliases["SampleApp"]["btnOK"]["WaitProperty"]("Enabled", true, 15000))
Log["Error"]("The OK button didn't become enabled within 15 seconds.");
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. To check multiple properties, consider using object checkpoints inside a loop.