WaitProperty Method

Applies to TestComplete 14.30, last modified on November 21, 2019

Description

Use the WaitProperty method to pause the test execution until the specified object property achieves the specified value or until the specified timeout elapses.

Declaration

TestObj.WaitProperty(PropertyNamePropertyValueWaitTime)

TestObj A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
PropertyName [in]    Required    String    
PropertyValue [in]    Required    Variant    
WaitTime [in]    Optional    Integer Default value: -1   
Result Boolean

Applies To

All processes, windows, controls and onscreen objects.

View Mode

This method is available in the Object Browser panel and in other panels and dialogs in both Basic and Advanced view modes.

Parameters

The method has the following parameters:

PropertyName

The name of the desired property.

PropertyValue

The property value to wait for before continuing the test execution.

You can enter the item’s index (from 0) or its caption. The caption can contain asterisk (*) or question mark (?) wildcards or regular expressions. The asterisk (*) wildcard corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none). To specify more complicated parts of a caption, use regular expressions. For information on them, see the Remarks section below.

The caption can be case-sensitive or case-insensitive depending on the value of the Use case-sensitive parameters project setting. Regular expression patterns are always case-insensitive.

WaitTime

The number of milliseconds to wait for the specified property value. If WaitTime is 0, the method does not wait and returns immediately. If WaitTime is -1, the waiting time is specified by the Auto-wait timeout project property.

Note: If you are testing an Open Application, the WaitTime parameter is required. In case of a non-Open Application, the WaitTime parameter is optional and has the default value 0.

Result Value

If the property achieves the specified value within the timeout, the method returns True. Otherwise, if the timeout elapses before the property achieves the specified value, the method returns False.

Also, False if the object does not have the specified property.

Remarks

  • The WaitProperty method does not support indexed properties (that is, properties that require parameters). To wait until an indexed property becomes equal to a specific value, you can use a loop like the following:

    JavaScript, JScript

    while (statusBarObj.wText(0) != "Ready")
    {
      aqUtils.Delay(100);
      statusBarObj.Refresh();
    }

    Python

    while (statusBarObj.wText(0) != "Ready"):
      aqUtils.Delay(100)
      statusBarObj.Refresh()

    VBScript

    While statusBarObj.wText(0) <> "Ready"
      aqUtils.Delay 100
      statusBarObj.Refresh
    Wend

    DelphiScript

    while statusBarObj.wText[0] <> 'Ready' do
    begin
      aqUtils.Delay(100);
      statusBarObj.Refresh;
    end;

    C++Script, C#Script

    while (statusBarObj["wText"](0) != "Ready")
    {
      aqUtils["Delay"](100);
      statusBarObj["Refresh"]();
    }

  • Regular expressions should start with "regexp:", for example:

    obj = parent.Find("PropName", "regexp:gr[ae]y", 5)

    Regular expression patterns use the standard TestComplete syntax, but have the following specifics:

    • All patterns are case-insensitive. For example, "regexp:gr[ae]y" will match both "gray" and "GRAY".

    • Patterns search for partial matches. For example, regexp:notepad matches both "notepad" and "notepad++". To search for an exact match, use the ^ and $ anchors, for example "regexp:^notepad$".

    Native regular expressions of the scripting languages are not supported.

Example

The following example demonstrates how to use the WaitProperty method in scripts:

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

See Also

Waiting for Object State Changes
WaitChild Method

Highlight search results