FindChildByXPath Method (Page Objects)

Applies to TestComplete 14.60, last modified on April 22, 2021

Description

Use the FindChildByXPath method to find a child web element on a web page by the values of the element’s attributes. The search condition is specified using the XPath syntax. TestComplete searches the entire web page.

The method returns the first found object that matches the specified condition. To get several elements, use the EvaluateXPath method.

The function searches by the names of HTML elements and attributes. It does not use object names that are displayed in the Object Browser panel.

The function finds only web page elements. It does not find and return internal objects of Flash or Silverlight applications embedded into the tested web page.

The function does not find objects in WebView nested frames.

Note that the function uses the element's attributes, not properties. The attributes can be specified in the HTML code, or they can be added to the element by the setAttribute script function. See the description of the setAttribute function in the MSDN Library.

Declaration

TestObj.FindChildByXPath(XPath, SearchInFrames)

TestObj A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
XPath [in]    Required    String    
SearchInFrames [in]    Optional    Boolean Default value: True   
Result An object or a null object

Applies To

The method is applied to the following object:

Page

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:

XPath

Specifies the XPath search expression.

The following requirements must be met for the specified expression:

  • The search expression must comply with the XPath rules. For more information on them, see XPath documentation. For instance, you can find XPath Reference in the MSDN Library.

  • The search expression must contain the names of HTML elements and attributes. The function does not use object names that are displayed in the Object Browser panel.

  • The element and attributes names in the search expression are case-insensitive. That is, you can specify them either in the upper case, or in the lower case.

    However, the element and attribute values, which you specify in the search expression, are case-sensitive. For instance, image1.PNG, IMAGE1.PNG and Image1.png are different values for XPath. The search expression must specify values in the same case, in which they are specified in the source code of the page. To create case-insensitive search expressions, use XPath’s translate function:

    //IMG[translate(@src, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') = 'image1.png']

    See the documentation of XPath’s translate function in the MSDN Library for complete information about this function and its parameters.

  • In search expressions, you can use XPath 1.0 functions like contains, substring, starts-with and others.

    XPath 2.0 functions (like lower-case(), matches() and others), Microsoft extensions and other third-party extensions to XPath functions are not supported.

The table below contains some examples of XPath expressions that can be passed through the XPath parameter to search for web page elements matching the desired search criteria. Also, in the “Tips on Using XPath Expressions” section of the Finding Web Objects Using XPath Expressions topic, you can find some tips on specifying XPath expressions for the FindChildByXPath method.

Expression Description
//IMG[contains(@src, 'plusBtn.gif')] All IMG elements whose src attribute contains the plusBtn.gif substring.
//A[starts-with(@href, 'javascript:')] All A elements whose href attribute starts with the javascript: prefix.
//DIV[@class='CodeExample']/P[1] All P elements that are located at the first position within DIV elements whose class attribute is set to CodeExample.
//*[@align='center'] All web page elements that have the align attribute set to center.
//UL/* A collection of direct children of any UL element.
//UL[@id='ProductList']/LI[last()] The last LI element within the UL element that has the id attribute set to ProductList.
//DIV//A All A elements that are descendants of any DIV element.

SearchInFrames

Specifies whether the function should search within the frames' content. If it is True (default), FindChildByXPath will search within the whole object hierarchy. If it is False, the content of the frames will be excluded from the search.

Result Value

The FindChildByXPath function searches for all the web elements, including those that are not displayed in the Object Tree. It finds a set of objects that match the search criteria and then returns the result using the following rules:

  • If only one element matches the search condition, the function returns this object.

  • If several elements match the search condition, the function returns the first found object that resides in the Object Tree. If none of the found objects resides in the Object Tree, the function returns the first element from the found set.

  • If the search failed, FindChildByXPath returns a null object (Nothing in VBScript, nil in DelphiScript, None in Python, null in JavaScript, JScript, C++Script and C#Script).

To search for multiple objects, use the EvaluateXPath method.

Remarks

In cross-platform web tests, we recommend that you use the FindElement (or WaitElement) method instead.

Example

The following example demonstrates how you can use the FindChildByXPath method in scripts:

JavaScript
JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript

function evalChildByXPath()
{
  // Obtain the Page object
  let url = "http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type";
  Browsers.Item(btIExplorer).Run(url);
  let page = Sys.Browser("*").Page("*");

  // Call the function
  let obj = page.FindChildByXPath("//button[@type='submit']", true);

  // Check the result
  if (!strictEqual(obj, null))
  {
    // If the element was found, click it
    obj.Click();
  }
  else
  {
    // If the element was not found, post a message to the log
    Log.Error("The element was not found.");
  }
}

JScript

function evalChildByXPath()
{
  // Obtain the Page object
  var url = "http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type";
  Browsers.Item(btIExplorer).Run(url);
  var page = Sys.Browser("*").Page("*");

  // Call the function
  var obj = page.FindChildByXPath("//button[@type='submit']", true);

  // Check the result
  if (obj != null)
  {
    // If the element was found, click it
    obj.Click();
  }
  else
  {
    // If the element was not found, post a message to the log
    Log.Error("The element was not found.");
  }
}

Python

def evalChildByXPath():
  # Obtain the Page object
  url = "http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type"
  Browsers.Item[btIExplorer].Run(url)
  page = Sys.Browser("*").Page("*")
 
  # Call the function
  obj = page.FindChildByXPath('//button[@type="submit"]', True)
 
  # Check the result 
  if (GetVarType(obj) != varNull):
    # If the element was found, click it
    obj.Click()
  else:
    # If the element was not found, post a message to the log
    Log.Message('The element was not found.')

VBScript

Sub evalChildByXPath
  Dim url, page, obj
 
  ' Obtain the Page object
  url = "http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type"
  Browsers.Item(btIExplorer).Run url
  Set page = Sys.Browser("*").Page("*")
 
  ' Call the function
  Set obj = page.FindChildByXPath("//button[@type='submit']", True)
 
  ' Check the result
  If Not obj is Nothing Then
    ' If the element was found, click it
    obj.Click
  Else
    ' If the element was not found, post a message to the log
    Log.Error "The element was not found."
  End If
End Sub

DelphiScript

procedure evalChildByXPath;
var url, page, obj;
begin
  // Obtain the Page object
  url := 'http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type';
  Browsers.Item(btIExplorer).Run(url);
  page := Sys.Browser('*').Page('*');
 
  // Call the function
  obj := page.FindChildByXPath('//button[@type="submit"]', true);
 
  // Check the result
  if GetVarType(obj) <> varNull then
  begin
    // If the element was found, click it
    obj.Click;
  end
  else
  begin
    // If the element was not found, post a message to the log
    Log.Message('The element was not found.');
  end;
end;

C++Script, C#Script

function evalChildByXPath()
{
  // Obtain the Page object
  var url = "http://www.w3schools.com/tags/tryit.asp?filename=tryhtml_button_type";
  Browsers["Item"](btIExplorer)["Run"](url);
  var page = Sys["Browser"]("*")["Page"]("*");
 
  // Call the function
  var obj = page["FindChildByXPath"]("//button[@type='submit']", true);
 
  // Check the result
  if (obj != null)
  {
    // If the element was found, click it
    obj["Click"]();
  }
  else
  {
    // If the element was not found, post a message to the log
    Log["Error"]("The element was not found.");
  }
}

See Also

EvaluateXPath Method (Page Objects)
Default Web Testing
Finding Web Objects Using XPath Expressions
Find Web Objects
Find Method
FindAll Method
FindChild Method
FindAllChildren Method

Highlight search results