FindEx Method

Description

Use the FindEx method to search for the desired object in the object hierarchy within the specified timeout interval. This method searches for an object with the specified values of the specified properties. If such an object does not exist, the method refreshes the object tree and tries to find the object again. It keeps doing this until the object is found or until the timeout elapses.

If you do not want to use a timeout, you can set it to zero, or use the Find method.

You can use either one or multiple properties for the search. The search starts from the testedObj object and continues down the object hierarchy to the specified depth.

The FindEx method is similar to FindChildEx. The difference between them is that FindChildEx only searches in child objects, while FindEx also searches in the testedObj object.

Declaration

Applies To

View Mode

To view this method in the Object Browser panel and in other panels and dialogs, activate the Advanced view mode.

Parameters

The method has the following parameters:

PropNames

A property or an array of properties by which the method will search for an object.

You can view the list of object properties and their values in the Object Browser. See Exploring Object Properties and Methods in the Object Browser.

For web applications and hybrid mobile applications, you can also specify names of native web attributes (since TestComplete treats native web attributes as object properties). See Accessing Native Web Attributes and Methods for details.

We do not recommend using the VisibleOnScreen property in search criteria. It can significantly decrease your test performance because it may take some time for TestComplete to get this property’s value, and TestComplete will have to get the value for every object it checks during the search.

PropValues

A value of a single property or an array of values of properties that the PropNames parameter specifies.

Values 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 the value, use regular expressions. For information on them, see the Remarks section below.

Values can be case-sensitive or case-insensitive depending on the Use case-sensitive parameters setting of your current project. Regular expression patterns are always case-insensitive.

You can view the list of object properties and their values in the Object Browser. See Exploring Object Properties and Methods in the Object Browser.

Depth

A zero-based integer number that specifies the level of objects where FindEx will search for the desired object. If Depth is 0, it means that the method will search only in testObj. If Depth is 1 (default), FindEx will search in testObj and its child objects, if Depth is 2, FindEx will search in testObj and its child and grandchild objects, and so on. To search in the whole testObj hierarchy, use a Depth value that is greater than the number of child levels in the hierarchy, for example, 20000.

RefreshTree

TestComplete performs the search in the cached copy of the object hierarchy, which may not correspond to the actual hierarchy of objects in the tested application. This may happen, for instance, if the actions that precedes the search caused changes in the application state. The RefreshTree parameter lets you specify what TestComplete should do if no object matching the search criteria was found in the cached object tree. If it is True (default), TestComplete will refresh the cached object tree and perform the search once again. If it is False, TestComplete will not refresh the object tree and will return a stub object indicating that the search failed.

Timeout

Specifies the time, in milliseconds, for which the FindEx method will try to find the specified object. If the Timeout is 0, the method will search for the object only once, like the Find method. If the Timeout is -1, the waiting time is equal to the auto-wait timeout option.

Result Value

The object that has the specified values of the specified properties. This can be either the testedObj object or one of its child, grandchild or great grandchild objects that matches the specified search conditions.

If no object matching the search criteria was found, the FindEx method returns a stub object that only contains the Exists property equal to False. So, you can check the Exists property value of the returned object to determine whether the search was successful.

Remarks

• The actual waiting time can be longer than the specified timeout, because TestComplete analyzes the object tree.

• To call the FindEx method in a keyword test, you can use the Call Object Method or Run Code Snippet operation. A possible alternative is to use the Find Object operation.

• The project property Object search strategy controls whether the method uses depth-first or breadth-first search.

• When the FindEx method is used to search for an object by its name (the Name property), TestComplete ignores spaces and the following characters in the name:

  ( ) [ ] . , " '

  This behavior is intended to eliminate differences between the object name syntax in different scripting languages during the search. This way, for example, FindEx can search for the Notepad process by any of the following names: Process("notepad") (VBScript, JavaScript, JScript and Python syntax), Process('notepad') (DelphiScript syntax) and ["Process"]("notepad") (C++Script and C#Script syntax).

  In general, it is not recommended to use the Name property with FindEx; consider using other properties instead. For example, Name is a complex value that is composed of other properties, such as WndClass or WndCaption, so you can search by a combination of these individual properties.

• To obtain an object by its name, you can also use the following techniques:

  • If you know the object name, you can refer to the object directly by this name:

    JavaScript, JScript

    Python

    VBScript

    DelphiScript

    C++Script, C#Script

    JavaScript, JScript

    var wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad");

    Python

    wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad")

    VBScript

    Set wndNotepad = Sys.Process("notepad").Window("Notepad", "Untitled - Notepad")

    DelphiScript

    wndNotepad := Sys.Process('notepad').Window('Notepad', 'Untitled - Notepad');

    C++Script, C#Script

    var wndNotepad = Sys["Process"]("notepad")["Window"]("Notepad", "Untitled - Notepad");

  • If an object name is specified as a string in your test (for example, if it is stored in a script variable), you can get the object by "evaluating" the string holding its name. For this purpose, you can use the following functions: eval in JavaScript, JScript, Python, C#Script and C++Script, Eval in VBScript and Evaluate in DelphiScript. The following example demonstrates this approach:

    JavaScript, JScript

    Python

    VBScript

    DelphiScript

    C++Script, C#Script

    JavaScript, JScript

    function NotepadTest()
    {
      var strObjName, p, wndNotepad;
    
      strObjName = "Window(\"Notepad\", \"* - Notepad\")";
    
      // Store the parent object to a variable
      p = Sys.Process("notepad");
    
      // Obtain the object by its Name property
      // p is the name of the variable that holds the parent object
      wndNotepad = eval("p." + strObjName);
    
      Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName);
    }

    Python

    def NotepadTest():
      strObjName = "Window(\"Notepad\", \"* - Notepad\")"
    
      # Store the parent object to a variable
      p = Sys.Process("notepad")
    
      # Obtain the object by its Name property
      # p is the name of the variable that holds the parent object
      wndNotepad = eval("p." + strObjName)
    
      Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName)

    VBScript

    Sub NotepadTest
      Dim strObjName, p, wndNotepad
    
      strObjName = "Window(""Notepad"", ""* - Notepad"")"
    
      ' Store the parent object to a variable
      Set p = Sys.Process("notepad")
    
      ' Obtain the object by its Name property
      ' p is the name of the variable that holds the parent object
      Set wndNotepad = Eval("p." & strObjName)
    
      Log.Picture wndNotepad, "Notepad window", wndNotepad.FullName
    End Sub

    DelphiScript

    procedure NotepadTest;
    var strObjName, p, wndNotepad;
    begin
      strObjName := 'Window(''Notepad'', ''* - Notepad'')';
    
      // Store the parent object to a variable
      p := Sys.Process('notepad');
    
      // Obtain the object by its Name property
      // p is the name of the variable that holds the parent object
      wndNotepad := Evaluate('p.' + strObjName);
    
      Log.Picture(wndNotepad, 'Notepad window', wndNotepad.FullName);
    end;

    C++Script, C#Script

    function NotepadTest()
    {
      var strObjName, p, wndNotepad;
    
      strObjName = "[\"Window\"](\"Notepad\", \"* - Notepad\")";
    
      // Store the parent object to a variable
      p = Sys["Process"]("notepad");
    
      // Obtain the object by its Name property
      // p is the name of the variable that holds the parent object
      wndNotepad = eval("p" + strObjName);
    
      Log.Picture(wndNotepad, "Notepad window", wndNotepad.FullName);
    }

• 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 code demonstrates searching for an object by one property. It searches for a control with the caption "Font style" among all child objects of the Notepad process. The control belongs to the Font dialog that Notepad shows when you select Format | Font from Notepad’s main menu. If the object does not exist, the method will try to find it for ten seconds. We use large Depth (1000) in the sample code as we do not know at which level in the object hierarchy the control resides.

def FindControlByOneProperty():
  
  # Searches for the control
  p = Sys.Process("Notepad")
  control = p.FindEx("WndCaption", "Font st&yle:", 1000, True, 6000)

  # Processes the search results
  if (control.Exists):
    Log.Message(control.FullName)
  else:
    Log.Error("The object was not found.")

The following code demonstrates searching for an object by several properties. It searches for a visible control with caption “Font style” within the Notepad process. We use large value of the Depth parameter in the sample code as we do not know at which level in the object hierarchy the button resides. The Timeout is equal to -1, which means that the method will use the auto-wait timeout.

def FindControlByTwoProperties():

  # Creates arrays of property names and values
  PropArray = ["WndCaption", "Visible"]
  ValuesArray = ["Font st&yle:", True]

  # Searches for the object
  p = Sys.Process("Notepad"); 
  obj = p.FindEx(PropArray, ValuesArray, 1000, True, -1);

  # Processes the search results
  if(obj.Exists):
    Log.Message(obj.FullName)
  else:
    Log.Error("The object was not found.")

For an example of using the FindEx method with web pages, see Finding Web Objects Using Common Find Methods.

See Also

FindChildEx Method
FindChild Method
FindAll Method
FindAllChildren Method
FindId Method
Find Method
Child Method
WaitChild Method