Sys.Browser Method

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

Description

The Sys.Browser method lets you access a running web browser application. You can use it to access a specific web browser, for example, Sys.Browser("iexplore"), or an arbitrary browser as in Sys.Browser() (see the parameters description below).

Once you have obtained the Browser object in your test, you can refer to its child Page and BrowserWindow objects or read the browser process information from the Browser object.

The Sys.Browser method does not launch a browser - it accesses a browser that is already running. To launch a browser from tests, use the Run Browser keyword test operation or the BrowserInfo.Run scripting method.
To check if a browser is running, use the Sys.WaitBrowser method rather than Sys.Browser. This way you will avoid the “Unable to find the object” error in case the specified browser is not running. For more information, see Check if Browser Is Running.

Declaration

Sys.Browser(BrowserNameBrowserIndex)

BrowserName [in]    Optional    String Default value: *   
BrowserIndex [in]    Optional    Integer Default value: 1   
Result A Browser object

Applies To

The method is applied to the following object:

Sys

Parameters

The method has the following parameters:

BrowserName

The browser process name. Possible values are:

Value Description
* Default. The asterisk wildcard matches the currently used browser, that is, the one that was launched previously using the Run Browser keyword test operation or the BrowserInfo.Run scripting method.
iexplore Microsoft Internet Explorer
edge Microsoft Edge
firefox Mozilla Firefox
chrome Google Chrome

If this parameter is omitted, it means the same as * - the currently used browser.

BrowserIndex

The browser process index (1-based) among other browser processes with the same name. For example, if you have two Firefox versions installed and both of them are currently running, the Firefox process that was launched first has BrowserIndex of 1 and the other one has BrowserIndex of 2. It is the same with 32-bit and 64-bit versions of Internet Explorer on 64-bit Windows.

If you have only one version of each browser installed, you can omit this parameter.

Result Value

A Browser object corresponding to the specified web browser.

Remarks

  • If the specified web browser is not running, the Sys.Browser method posts an error to the test log. To avoid the error, use the Sys.WaitBrowser method to check if the browser exists. For more information, see Check if Browser Is Running.

  • When several browsers are running simultaneously and neither the BrowserName nor the BrowserIndex parameter is specified, TestComplete posts the "Ambiguous browser recognition" warning and selects an arbitrary browser.

    However, in order to reduce ambiguous recognition issues, TestComplete can select the appropriate browser depending on the URL of the requested page. If the Browser object that was returned by the Sys.Browser() method does not contain the Page object with the specified URL while another running browser displays such a page, TestComplete automatically reassigns the method’s resulting value to the Browser object that corresponds to the browser displaying the page with the requested URL.

  • If you use Name Mapping and it includes the browser object, you typically refer to browsers as Aliases.browser rather than use the Sys.Browser method.

  • In VBScript and DelphiScript, you can omit parentheses in the Sys.Browser method call when using default parameter values, for example:

    VBScript

    Sys.Browser.Close ' Same as Sys.Browser().Close

    DelphiScript

    Sys.Browser.Close; // Same as Sys.Browser().Close

    In JavaScript, JScript, Python, C#Script and C++Script, you must always use parentheses even if the parameter values are omitted:

    JavaScript, JScript

    Sys.Browser().Close();

    Python

    Sys.Browser().Close()

    C++Script, C#Script

    Sys["Browser"]()["Close"]();

  • The Window 10 October 2018 update changed the behavior of the Edge browser. When you close the browser, the browser process is not terminated, it remains in the system. So, calls to Sys.Browser("*") or Sys.Browser() will return the Browser object that matches the running instance of Edge. This might cause issues for tests that check whether the browser is running or not. Keep this in mind and update your tests, if needed.

  • The Sys.Browser method is provided by the Web Testing plugin. It is installed and enabled automatically.

Example

The following example demonstrates how to use the Sys.Browser method in scripts:

JavaScript, JScript

function WebSample()
{

  Browsers.Item(btIExplorer).Run("http://smartbear.com/");

  // Obtains the browser process
  var browser = Sys.Browser("iexplore");
  // Obtains the page currently opened in Internet Explorer
  var page = browser.Page("*");

}

Python

def WebSample():

  Browsers.Item[btIExplorer].Run("http://smartbear.com/");

  # Obtains the browser process
  browser = Sys.Browser("iexplore");
  # Obtains the page currently opened in Internet Explorer
  page = browser.Page("*");

VBScript

Sub WebSample

  Browsers.Item(btIExplorer).Run("http://smartbear.com/")

  ' Obtains the browser process
  Set browser = Sys.Browser("iexplore")
  ' Obtains the page currently opened in Internet Explorer
  Set page = browser.Page("*")

End Sub

DelphiScript

procedure WebSample();
var browser, page;
begin

  Browsers.Item(btIExplorer).Run('http://smartbear.com/');

  // Obtains the browser process
  browser := Sys.Browser('iexplore');
  // Obtains the page currently opened in Internet Explorer
  page := browser.Page('*');

end;

C++Script, C#Script

function WebSample()
{

  Browsers["Item"](btIExplorer)["Run"]("http://smartbear.com/");

  // Obtains the browser process
  var browser = Sys["Browser"]("iexplore");
  // Obtains the page currently opened in Internet Explorer
  var page = browser["Page"]("*");

}

See Also

WaitBrowser Method
Browser Object
Default Web Testing
Understanding Web Object Identification and Object Models

Highlight search results