Description

Use the EvaluateXPath method to find an 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 an array of the matched elements. To search for a single element, use the FindChildByXPath 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.EvaluateXPath(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 array or null Variant value

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 EvaluateXPath 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), EvaluateXPath will search within the whole object hierarchy. If it is False, the content of the frames will be excluded from the search.

Result Value

If the search condition matches one or several elements and the search was successful, the function returns an array of found objects.

Tip: To search for a single element, use the FindChildByXPath method.

If you use the EvaluateXPath method and only one element matches the search condition, the method returns an array that contains one item. If a TestComplete test object matches the found object, then the array item contains this test object. If there is no matching test object (for instance, the XPath expression returns an attribute), the array item contains the appropriate HTML object.

Note for JScript, C#Script and C++Script users: The returned array is Variant-compatible. It can be used as is in JavaScript, Python, VBScript and DelphiScript, but if you use JScript, C#Script or C++Script, you have to convert this array to the format supported by the JScript engine. To do this, you can use the toArray() method of the variant array:

JScript, C#Script, C++Script
Copy Code

JScript, C#Script, C++Script

var JScript_Array = Variant_Array.toArray()

The use of this object is demonstrated in the Example section below.
If the search failed, EvaluateXPath returns a null Variant value.
If the search expression is a call to an XPath function, EvaluateXPath returns the result of this function.

The code snippet in the Example section below demonstrates how you can check the function’s result.

Remarks

In cross-platform web tests, we recommend that you use the FindElement (or WaitElement) method instead.
EvaluateXPath method may take a long time in Chrome browser. If it does, use other methods to find an object, or use a different browser.

Example

The following example demonstrates how you can use the EvaluateXPath method to search for a web page element by one of its attributes:

JavaScript

function evalXPath()
{

   // 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 arr = page.EvaluateXPath("//button[contains(@type, 'submit')]");

   // Check the result
   if (!strictEqual(arr, null))
   {
     // and click the first element that was found
    arr[0].Click(); // Note we refer to the array item
   }
   else
   {
     // If nothing was found, post a message to the log
     Log.Error("Nothing was found.");
   }
}

JScript

function evalXPath()
{

   // 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 tmp = page.EvaluateXPath("//button[contains(@type, 'submit')]");

   // Check the result
   if (tmp != null)
   {
     // Convert the array to the JScript-compatible format
     var arr = tmp.toArray();
     // and click the first element that was found
    arr[0].Click(); // Note we refer to the array item
   }
   else
   {
     // If nothing was found, post a message to the log
     Log.Error("Nothing was found.");
   }
}

Python

def evalXPath():
  # 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 
  arr = page.EvaluateXPath('//button[contains(@type, "submit")]')

  # Check the result 
  if GetVarType(arr) != varNull:
    # Click the first element that was found 
    arr[0].Click() # Note we refer to the array item 
  else: 
    # If nothing was found, post a message to the log 
    Log.Message("Nothing was found.")

VBScript

Sub evalXPath
   Dim url, page, arr, i

   ' 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
   arr = page.EvaluateXPath("//button[contains(@type, 'submit')]")

   ' Check the result
   If Not IsNull(arr) Then
     ' Click the first element that was found
       arr(0).Click ' Note we refer to the array item

   Else
     ' If nothing was found, post a message to the log
     Log.Error "Nothing was found."
   End If
End Sub

DelphiScript

procedure evalXPath;
var url, page, arr, i;
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
   arr := page.EvaluateXPath('//button[contains(@type, "submit")]');

   // Check the result
   if GetVarType(arr) <> varNull then
   begin
     // ' Click the first element that was found
     arr[0].Click; // Note we refer to the array item
   end
   else
     begin
       // If nothing was found, post a message to the log
       Log.Message('Nothing was found.');
     end;
end;

C++Script, C#Script

function evalXPath()
{

  // 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 tmp = page["EvaluateXPath"]("//button[contains(@type, 'submit')]");

  // Check the result
  if (tmp != null)
  {
    // If the element was found,
    // convert the array to the JScript-compatible format
    var arr = tmp["toArray"]();
    // and click the first element that was found
   arr[0]["Click"](); // Note we refer to the array item
  }
  else
  {
    // If nothing was found, post a message to the log
    Log["Error"]("Nothing was found.");
  }
}

EvaluateXPath Method (Page Objects)

Description

Declaration

Applies To

View Mode

Parameters

Result Value

Remarks

Example

See Also