Sys.WaitBrowser Method

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

Description

The Sys.WaitBrowser method instructs TestComplete to wait until the specified browser process exists in the system or until the timeout is reached.

You typically use this method in combination with the Exists property to check if a browser is currently running. See the Example section below and also Check if Browser Is Running.

Note: The Sys.WaitBrowser method is usually used in scripted tests that do not use Name Mapping. In keyword tests, you can define a custom object waiting timeout directly for specific operations using the Set Auto-Wait Timeout for Operations command of the context menu. You can also use the If Object keyword test operation to check if the browser is running.
The Sys.WaitBrowser method does not launch a browser - it checks if the specified browser process is running. To launch a browser from tests, use the Run Browser keyword test operation or the BrowserInfo.Run scripting method.

Declaration

Sys.WaitBrowser(BrowserName, Timeout, BrowserIndex)

BrowserName [in]    Optional    String Default value: *   
Timeout [in]    Optional    Integer Default value: 0   
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.

Timeout

The time, in milliseconds, to wait for the browser process to become available. If Timeout is 0, the method searches for the specified browser once and then returns immediately. If Timeout is -1, the waiting time is infinite.

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

If the specified browser process was found, the method returns the corresponding Browser object.

If the browser process was not found during the timeout, the method returns a stub object with the Exists property equal to False. So, you can check the Exists property of the returned object to see whether the browser was found.

Remarks

  • Unlike the Browser method, WaitBrowser does not post an error message to the test log if the specified browser is not running. To check whether the browser was found, examine the Exists property of the returned object.

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

    VBScript

    If Sys.WaitBrowser.Exists Then ... ' Same as Sys.WaitBrowser().Exists

    DelphiScript

    if Sys.WaitBrowser.Exists then ... // Same as Sys.WaitBrowser().Exists

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

    JavaScript, JScript

    if (Sys.WaitBrowser().Exists) ...

    Python

    if (Sys.WaitBrowser().Exists) ...

    C++Script, C#Script

    if (Sys["WaitBrowser"]()["Exists"]) ...

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

Example

The following examples checks if Internet Explorer is running:

JavaScript, JScript

if (Sys.WaitBrowser("iexplore").Exists)
  Log.Message("Internet Explorer is running.")
else
  Log.Message("Internet Explorer is not running.");

Python

if (Sys.WaitBrowser("iexplore").Exists):
  Log.Message("Internet Explorer is running.")
else:
  Log.Message("Internet Explorer is not running.")

VBScript

If Sys.WaitBrowser("iexplore").Exists Then
  Log.Message "Internet Explorer is running."
Else
  Log.Message "Internet Explorer is not running."
End If

DelphiScript

if Sys.WaitBrowser('iexplore').Exists then
  Log.Message('Internet Explorer is running.')
else
  Log.Message('Internet Explorer is not running.');

C++Script, C#Script

if (Sys["WaitBrowser"]("iexplore")["Exists"])
  Log["Message"]("Internet Explorer is running.")
else
  Log["Message"]("Internet Explorer is not running.");

If you need to keep a reference to the returned browser process for later use in the test, use code as follows:

JavaScript, JScript

var p = Sys.WaitBrowser("iexplore", 10000); // 10 sec timeout
if (p.Exists)
{
  Log.Message("Internet Explorer is running.");

  // Do something with p
  ...
}
else
  Log.Message("Internet Explorer is not running.");

Python

p = Sys.WaitBrowser("iexplore", 10000) # 10 sec timeout
if (p.Exists):
  Log.Message("Internet Explorer is running.")

  # Do something with p
  # ...
else:
  Log.Message("Internet Explorer is not running.")

VBScript

Set p = Sys.WaitBrowser("iexplore", 10000) ' 10 sec timeout
If p.Exists Then
  Log.Message "Internet Explorer is running."

  ' Do something with p
  ...
Else
  Log.Message "Internet Explorer is not running."
End If

DelphiScript

procedure Test;
var p;
begin
  p := Sys.WaitBrowser('iexplore', 10000); // 10 sec timeout
  if p.Exists then
  begin
    Log.Message('Internet Explorer is running.');

    // Do something with p
    ...
  end
  else
    Log.Message('Internet Explorer is not running.');
end;

C++Script, C#Script

var p = Sys["WaitBrowser"]("iexplore", 10000); // 10 sec timeout
if (p["Exists"])
{
  Log["Message"]("Internet Explorer is running.");

  // Do something with p
  ...
}
else
  Log["Message"]("Internet Explorer is not running.");

See Also

Browser Object
Browser Method
Classic Web Testing
Check if Browser Is Running
Waiting for an Object, Process or Window Activation

Highlight search results