Description

Use the Find method to search for the desired object in the object hierarchy. This method searches for an object with the specified values of the specified properties. 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 Find method is similar to FindChild. The difference between them is that FindChild only searches in child objects, while Find also searches in the testedObj object.

Declaration

TestObj.Find(PropNames, PropValues, Depth, RefreshTree)

TestObj	A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
PropNames	[in]	Required	Variant
PropValues	[in]	Required	Variant
Depth	[in]	Optional	Integer	Default value: 1
RefreshTree	[in]	Optional	Boolean	Default value: True
Result	Object

Applies To

All processes, windows, controls and onscreen objects.

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.

PropValues

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

Values can contain wildcards or regular expressions:

The asterisk (*) wildcard corresponds to a string of any length (including an empty string).
The question mark (?) wildcard corresponds to any single character (including none).
To specify more complicated sought-for patterns for property values, use regular expressions, in the following format: regexp:<pattern>. For example, regexp:gr[ae]y.

The property does not support native regular expression syntax, that is, the syntax provided by scripting languages. Use standard TestComplete (non-native) syntax to specify regular expressions.

Notes:
- 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$".
For detailed information on regular expression syntax, see Regular Expressions Syntax .

Depth

An integer number that specifies the level of objects where Find will search for the desired object. If Depth is less than or equal to 0, it means that the method will search only in testObj. If Depth is 1 (default), Find will search in testObj and its child objects, if Depth is 2, Find 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.

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 Find 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

As an alternative to using the Find method, to get a needed tested object, you can use Name Mapping. Specify the properties by which your tested object will be searched and store the object together with its search criteria in the Name Mapping repository for later use. To learn more, see Name Mapping.
We do not recommend that you use the VisibleOnScreen property in a search condition of the method. It may take much time for TestComplete to get the value of this property, and using it for searching for objects may decrease the test performance significantly.
To call the Find 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 Find 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, Find 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 Find; 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
  Copy Code
  
  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
  Copy Code
  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);
  }
In mobile tests, the identification criteria of the objects that the Find method returns are based on the internal properties that TestComplete assigns to objects. This differs from the objects you can get by using various FindElement, FindElements, and WaitElements methods. Their identification criteria are based on the accessibility information the tested application provides. This makes the objects got by Find methods and those got by the FindElement, FindElements, and WaitElement methods incompatible.

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 is part of the Font dialog that is displayed when selecting Format | Font from Notepad’s main menu). We use large Depth (1000) in the sample code as we do not know at which level in the object hierarchy the control resides.

JavaScript, JScript

function FindControlByOneProperty()
{
  var p, control;

  // Searches for the control
  p = Sys.Process("Notepad");
  control = p.Find("WndCaption", "Font st&yle:", 1000);

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

Python

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

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

VBScript

Sub FindControlByOneProperty
  Dim p, control

  ' Searches for the control
  Set p = Sys.Process("Notepad")
  Set control = p.Find("WndCaption", "Font st&yle:", 1000)

  ' Processes the search results
  If control.Exists Then
    Log.Message control.FullName
  Else
    Log.Error "The object was not found."
  End If
End Sub

DelphiScript

procedure FindControlByOneProperty;
var
  p, control : Variant;
begin
  // Searches for the control
  p := Sys.Process('Notepad');
  control := p.Find('WndCaption', 'Font st&yle:', 1000);

  // Processes the search results
  if control.Exists then
    Log.Message(control.FullName)
  else
    Log.Error('The object was not found.');
end;

C++Script, C#Script

function FindControlByOneProperty()
{
  var p, control;

  // Searches for the control
  p = Sys["Process"]("Notepad");
  control = p["Find"]("WndCaption", "Font st&yle:", 1000);

  // Processes the search results
  if (control["Exists"])
    Log["Message"](control["FullName"]);
  else
    Log["Error"]("The object was not found.");
}

The following code shows searching for an object by several properties. It searches for a visible control with caption “Font style” within the Notepad process. The control belongs to the Font dialog that Notepad shows when you select Format | Font from Notepad’s main menu. 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.

JavaScript, JScript

function Test()
{
  var PropArray, ValuesArray, p, obj;

  // Creates arrays of property names and values
  PropArray = new Array("WndCaption", "Visible");
  ValuesArray = new Array("Font st&yle:", true);

  // Searches for the object
  p = Sys.Process("Notepad");
  obj = p.Find(PropArray, ValuesArray, 1000);

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

Python

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.Find(PropArray, ValuesArray, 1000)

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

VBScript

Sub Test
  Dim PropArray, ValuesArray, p, obj

  ' Creates arrays of property names and values
  PropArray = Array("WndCaption", "Visible")
  ValuesArray = Array("Font st&yle:", True)

  ' Searches for the object
  Set p = Sys.Process("Notepad")
  Set obj = p.Find(PropArray, ValuesArray, 1000)

  ' Processes the search results
  If obj.Exists Then
    Log.Message obj.FullName
  Else
    Log.Error "The object was not found."
  End If
End Sub

DelphiScript

procedure Test;
var
  PropArray, ValuesArray, p, obj : Variant;
begin
  // Creates arrays of property names and values
  PropArray := CreateVariantArray(0, 1);
  PropArray[0] := 'WndCaption';
  PropArray[1] := 'Visible';
  ValuesArray := CreateVariantArray(0, 1);
  ValuesArray[0] := 'Font st&yle:';
  ValuesArray[1] := True;

  // Searches for the object
  p := Sys.Process('Notepad');
  obj := p.Find(PropArray, ValuesArray, 1000);

  // Processes the search results
  If obj.Exists Then
    Log.Message(obj.FullName)
  else
    Log.Error('The object was not found.');
end;

C++Script, C#Script

function Test()
{
  var PropArray, ValuesArray, p, obj;

  // Creates arrays of property names and values
  PropArray = new Array("WndCaption", "Visible");
  ValuesArray = new Array("Font st&yle:", true);

  // Searches for the object
  p = Sys["Process"]("Notepad");
  obj = p["Find"](PropArray, ValuesArray, 1000);

  // 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 Find method with web pages, see Finding Web Objects Using Common Find Methods.

Find Method

Description

Declaration

Applies To

View Mode

Parameters

Result Value

Remarks

Example

See Also