QuerySelector Method (Page Objects)

Applies to TestComplete 15.0, last modified on November 17, 2021

Description

Returns the first web page element that matches the specified group of CSS selectors. To find multiple elements, use the QuerySelectorAll method.

Declaration

TestObj.QuerySelector(Selector)

TestObj A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
Selector [in]    Required    String    
Result Object

Applies To

The Page and UIPage objects and all the child elements of these 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 parameter:

Selector

A string containing one or more CSS selectors.

The table below demonstrates some examples of CSS selectors, which you can pass to the QuerySelector method in order to search for the desired web page elements.

Selector Description
h3 All H3 elements.
#infobox An element with the ID "infobox".
.nav All elements with the class "nav".
div,p All DIV elements and all P elements.
div p All P elements inside DIV elements.
img.thmb All IMG elements of the "thmb" class.
a:link All unvisited links.
a[target=blank] All links that open in a new window.
a[src^="https"] All links whose src attribute value begins with "https".
li:first-of-type All LI elements that are the first item in their parent elements.
p:nth-child(2) All P elements that are located at the second position within their parent elements.

You can find more information about the CSS selector syntax in the Finding Web Objects Using CSS Selectors topic. For a complete reference, see the W3C Selectors Level 3 Specification.

Result Value

If a TestComplete web object matches the specified selector, then the method returns this object.

If there is no matching TestComplete test object, the method returns the appropriate HTML object.

If neither the matching test object, nor the HTML object was found, the method returns an empty value (null in JavaScript, JScript, C#Script and C++Script, None in Python, Nothing in VBScript, nil in DelphiScript).

Tip: To find multiple elements, use the QuerySelectorAll method.

Remarks

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

  • When the method is called for Page objects, it searches the entire web page. If it is called for a particular web page element, then it searches within the children of that element. When the method is called for the UIPage object or its child objects, the search is performed within the UI controls.

  • The search is performed within the current web page. If the tested web page contains HTML frames displaying other web pages, then to search for the desired element within a frame, you should call Frame.QuerySelector() instead of Page.QuerySelector().

Example

The following code fragment demonstrates how to use the QuerySelector method and verify its result. The sample code navigates to SmartBear web site and searches for the first link that opens in a new window that is located inside the DIV element with the ID equal to "main-nav".

JavaScript

function Test()
{
  var TestedPage, CSSSelector, res;

  Browsers.Item(btChrome).Run("https://smartbear.com/");
  TestedPage = Sys.Browser("*").Page("https://smartbear.com/");

  CSSSelector = "div#main-nav a[target=blank]";
  
  // Call the function
  res=TestedPage.QuerySelector(CSSSelector);
  // Check the result
  if (!strictEqual(res, null))
      // If the element was found, output its HTML code
      Log.Message(res.outerHTML);
  else
      // If the element was not found, post a warning to the log
      Log.Warning("The element was not found.");
}

JScript

function Test()
{
  var TestedPage, CSSSelector, res;

  Browsers.Item(btChrome).Run("https://smartbear.com/");
  TestedPage = Sys.Browser("*").Page("https://smartbear.com/");

  CSSSelector = "div#main-nav a[target=blank]";
  
  // Call the function
  res=TestedPage.QuerySelector(CSSSelector);
  // Check the result
  if (res != null)
      // If the element was found, output its HTML code
      Log.Message(res.outerHTML);
  else
      // If the element was not found, post a warning to the log
      Log.Warning("The element was not found.");
}

Python

def Test():

  Browsers.Item[btChrome].Run("https://smartbear.com/")
  TestedPage = Sys.Browser("*").Page("https://smartbear.com/")

  CSSSelector = "div#main-nav a[target=blank]" 
  
  # Call the function
  res=TestedPage.QuerySelector(CSSSelector)
  # Check the result
  if (res != None):
      # If the element was found, output its HTML code
      Log.Message(res.outerHTML)
  else:
      # If the element was not found, post a warning to the log
      Log.Warning("The element was not found.")

VBScript

Sub Test
  Dim TestedPage, CSSSelector, res

  Browsers.Item(btChrome).Run("https://smartbear.com/")
  Set TestedPage = Sys.Browser("*").Page("https://smartbear.com/")

  CSSSelector = "div#main-nav a[target=blank]" 
  
  ' Call the function
  Set res=TestedPage.QuerySelector(CSSSelector)
  ' Check the result
  If Not res Is Nothing Then
      ' If the element was found, output its HTML code
      Log.Message(res.outerHTML)
  Else
      ' If the element was not found, post a warning to the log
      Log.Warning("The element was not found.")
  End If
End Sub

DelphiScript

procedure Test;
var TestedPage, CSSSelector, res;
begin
  Browsers.Item[btChrome].Run('https://smartbear.com/');
  TestedPage := Sys.Browser('*').Page('https://smartbear.com/');

  CSSSelector := 'div#main-nav a[target=blank]';
  
  // Call the function
  res:=TestedPage.QuerySelector(CSSSelector);
  // Check the result
  if res <> nil then
      // If the element was found, output its HTML code
      Log.Message(res.outerHTML)
  else
      // If the element was not found, post a warning to the log
      Log.Warning('The element was not found.');
end;

C++Script, C#Script

function Test()
{
  var TestedPage, CSSSelector, res;

  Browsers["Item"](btChrome)["Run"]("https://smartbear.com/");
  TestedPage = Sys["Browser"]("*")["Page"]("https://smartbear.com/");

  CSSSelector = "div#main-nav a[target=blank]";
  
  // Call the function
  res=TestedPage["QuerySelector"](CSSSelector);
  // Check the result
  if (res != null)
      // If the element was found, output its HTML code
      Log["Message"](res["outerHTML"]);
  else
      // If the element was not found, post a warning to the log
      Log["Warning"]("The element was not found.");
}

See Also

QuerySelectorAll Method (Page Objects)
Classic Web Testing
Find Web Objects
QuerySelectorAll Method (Page Objects)
NativeWebObject.Find Method (Page Objects)
Find Method
FindAll Method
FindChild Method
FindAllChildren Method
EvaluateXPath Method (Page Objects)

Highlight search results