Articles

[Collapse]TestComplete/viewarticle/88628/
 [Expand]General Information/viewarticle/88628/
 [Expand]Using Help System/viewarticle/81465/
 [Expand]Getting Started Tutorial/viewarticle/82003/
 [Expand]Using TestComplete/viewarticle/84431/
 [Expand]Testing Types/viewarticle/85355/
 [Expand]Applications Testing/viewarticle/83383/
 [Expand]Working With Application Objects and Controls/viewarticle/81481/
 [Expand]Samples and Tutorials/viewarticle/81997/
 [Collapse]References/viewarticle/82523/
  [Collapse]Test Objects/viewarticle/82423/
   [Expand]Controls and Objects/viewarticle/87889/
   [Collapse]Methods and Properties/viewarticle/83416/
    [Expand]Common Methods and Properties (Desktop)/viewarticle/88655/
    [Expand]Common Methods and Properties (Web)/viewarticle/82800/
    [Expand]A
    [Expand]B
    [Expand]C
    [Expand]D
    [Expand]E
    [Collapse]F
      wFieldCount Property (Specific to iOS AlertView Object)/viewarticle/83002/
      wFieldText Property (Specific to iOS AlertView Object)/viewarticle/86949/
      FileVersionInfo Property/viewarticle/80876/
      Find Method/viewarticle/80936/
      FindAll Method/viewarticle/80964/
      FindAllChildren Method/viewarticle/80662/
      FindChild Method/viewarticle/80676/
      FindChildByXPath Method (Page Objects)/viewarticle/81281/
      FindChildByXPath Method (UIPage Objects)/viewarticle/81267/
      FindChildByXPath Method (Web Objects)/viewarticle/81300/
      FindChildEx Method/viewarticle/81414/
      FindEx Method/viewarticle/81415/
      FindId Method/viewarticle/80950/
      FindRow Action/viewarticle/81139/
      FlatScrollBar Property (ListViewStyleEx Objects)/viewarticle/82433/
      FlexObject Property/viewarticle/81048/
      Focus Property (Specific to Flash List and Flex List Objects)/viewarticle/87526/
      Focus Property (Specific to MSAA List Objects)/viewarticle/85538/
      wFocus Property (Android Controls)/viewarticle/85319/
      wFocus Property (ListBox Controls)/viewarticle/84375/
      wFocus Property (ListView Controls)/viewarticle/84804/
      Focused Property/viewarticle/83444/
      Focused Property (MSAA Objects)/viewarticle/87433/
      wFocused Property (ListView Controls)/viewarticle/84421/
      wFocused Property (Specific to InfragisticsWinListView Controls)/viewarticle/87220/
      wFocusedTab Property (Mobile Controls)/viewarticle/82610/
      wFocusedTab Property (Tab Controls)/viewarticle/83386/
      FocusedTab Property (Specific to MSAA TabList Objects)/viewarticle/88856/
      FocusedTab Property (Tab Controls)/viewarticle/86424/
      FocusedWindow Method (Desktop Objects)/viewarticle/83602/
      FocusItem Action (ListView Controls)/viewarticle/83585/
      Footer Property (Specific to Win32ListViewGroup Object)/viewarticle/83522/
      FooterAlign Property (Specific to Win32ListViewGroup Objects)/viewarticle/88318/
      wFormat Property (Header Controls)/viewarticle/82234/
      Frame Method (Web Objects)/viewarticle/86124/
      FriendlyName Property (Windows Store Processes)/viewarticle/85223/
      FullName Property/viewarticle/83370/
      FullRowSelect Property (ListViewStyleEx Objects)/viewarticle/86923/
    [Expand]G
    [Expand]H
    [Expand]I
    [Expand]J
    [Expand]K
    [Expand]L
    [Expand]M
    [Expand]N
    [Expand]O
    [Expand]P
    [Expand]Q
    [Expand]R
    [Expand]S
    [Expand]T
    [Expand]U
    [Expand]V
    [Expand]W
    [Expand]X
    [Expand]Y
    [Expand]Z
  [Expand]Scripting Objects/viewarticle/88052/
  [Expand]Project and Project Item Objects/viewarticle/84209/
  [Expand]TestComplete Events/viewarticle/83126/
  [Expand]Language Reference/viewarticle/87902/
  [Expand]User Form Components/viewarticle/83917/
   Regular Expressions Syntax/viewarticle/81060/
 [Expand]Other Tools That Help You Test Better/viewarticle/82893/
 [Expand]Licensing Guide/viewarticle/88365/
Updated: 7/26/2016 Applies To: TestComplete 12 Rating: AverageAverageAverageAverageAverage 2 vote(s) Click to rate: PoorNot badAverageGoodExcellent
Programming Reference

FindChild Method

Description

An object can have one or more child objects. For instance, processes are children of the Sys object and windows are children of processes. The FindChild method searches for a child object with the specified values of the specified properties.

The FindChild method is analogue to Find. The difference between them is that Find searches in the object and its child objects, while FindChild only searches in child objects.

Declaration

TestObj.FindChild(PropNamesPropValuesDepthRefresh)

   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: 0
Refresh [in] Optional Boolean Default value: True
Result Object  

Applies To

Parameters

The method has the following parameters:

PropNames

An array of strings containing the names of properties or a single property name. See the Remarks section for details. The method returns an object by the values of these properties (property).

For web 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

An array containing the values of the specified properties or a single property value (see Remarks).

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.

Depth

A zero-based number that sets the maximum level of the object’s hierarchy that the method will reach while searching for the specified object.

By default, the Depth is 0. The method will search for the specified object among immediate children of the testObj object.

If Depth is 1, the method will search among child objects of the testObj object and their child objects. If Depths is 2, the method will search among the testObj object’s child objects, their child and grandchild objects, and so on.

To search in the whole hierarchy of the testObj object’s child objects, use a Depth value that is greater than the number of child levels in the hierarchy, for example, 2000.

Refresh

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 Refresh 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. If no object matching the search criteria was found, the FindChild 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

  • To call the FindChild 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 FindChild 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, FindChild 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 FindChild; 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

      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

      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 searches for a visible window with the caption “Font style” among all child objects of the Notepad process. The window belongs to the Font dialog that Notepad shows when you select Format | Font from Notepad’s main menu.

JavaScript, JScript

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

  // Searches for the window
  p = Sys.Process("Notepad");
  w = p.FindChild(PropArray, ValuesArray, 5);

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

Python

def Test():
  
  # Creates arrays of property names and values
  PropArray = ["WndCaption", "Visible"]
  ValuesArray = ["Font st&yle:", True]
  # Searches for the window
  p = Sys.Process("Notepad")
  w = p.FindChild(PropArray, ValuesArray, 5)
  # Processes the search results
  if (w.Exists):
    Log.Message(w.FullName)
  else:
    Log.Error("The object was not found.")

VBScript

Sub Test
  Dim PropArray, ValuesArray, p, w

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

  ' Searches for the window
  Set p = Sys.Process("Notepad")
  Set w = p.FindChild(PropArray, ValuesArray, 5)

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

DelphiScript

procedure Test;
var PropArray, ValuesArray, p, w;
begin
  // Creates arrays of property names and values
  PropArray := ['WndCaption', 'Visible'];
  ValuesArray := ['Font st&yle:', true];

  // Searches for the window
  p := Sys.Process('Notepad');
  w := p.FindChild(PropArray, ValuesArray, 1000);

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

C++Script, C#Script

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

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

  // Searches for the window
  p = Sys["Process"]("Notepad");
  w = p["FindChild"](PropArray, ValuesArray, 5);

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

See also
FindAllChildren Method | Find Method | FindAll Method | FindId Method | Find Method | Child Method | WaitChild Method


© 2016 SmartBear Software. All rights reserved.
Email Send feedback on this document