Browser

3.1.1 Browser

Browser - Automate a Selenium driven web browser (since v5). An overview of the technology and configuration steps are being maintained in a separate document. The command supports the following actions:

• "Browser open" opens the selected web browser and loads the specified web page. The browser can be a local one or a remote one (Selenium Grid, supported since 6.3). Since version 8 the command can also open a new tab or a window.
• "Browser find" searches the web page for an element (an HTML tag) by the specified criteria and applies an optional action to it (click, type, submit, clear).
  • If the command does NOT specify an action and the element is not found it allows the script to continue. The search result (found/not found) is indicated to the script by the command exit code and the existence of the _WEB variables containing the element attributes.
  • If the command specifies the action and the element is not found it terminates the script. This behaviour is consistent with the Click and Drag commands.
  • To script actions like "apply action to an element if it exists and continues" use a pair of "Browser find" commands where the first one verifies the element existence and the second one applies the action.
• "Browser switch" switches among tabs or windows and/or updates the variables describing them. Supported since v8.
• "Browser close" closes the tab, window or the whole browser and eventually terminates the Selenium session.

Starting with release 8 most Browser command operations populate a set of variables describing the available tabs and windows as follows. You may also force refresh them by running "Browser switch" without any additional parameters:

SYNOPSIS

Local browser:

Browser open browser=<browser_code> [url=<web_page>] [args=<CLI_arguments>] [opt-<name>=<value>]

Remote browser:

Browser open browserName=<browser_code> hub=<hub_address> [url=<web_page>]

Open a new URL in an already opened browser:

Browser open url=<web_page> [target=<self|window|tab>]

* Red colour indicates obligatory parameters

OPTIONS

browser=<browser_code>

- The browser code name. The currently supported values are:

• "ie" - Microsoft Internet Explorer
• "edge" - Microsoft Edge
• "firefox" - Firefox (Gecko)
• "chrome" - Google Chrome
• "safari" - Safari (Mac OS X)
• "chromium" - requires the Chromium web driver plugin to be installed (v7.0+)

url=<web_page>

- The web page to be loaded, for example "https://www.t-plan.com".

args=<CLI_arguments>

- CLI arguments to be passed to the browser process if supported by the browser type. Supported since v7.0. See the CLI Arguments discussion in the Selenium document. 

opt-<name>=<value>

- A preference value to be passed to the browser process if the browser type supports it. Supported since v7.0. For example, Chrome uses the "download.default_directory" preference to set the default download directory. To redirect your downloads to C:\MyStuff use opt-download.default_directory="C:\MyStuff".

hub=<hub_address>

- The Selenium Grid hub address.

browserName=<browser_name>

- The hub recognized browser name.

target=<self|window|tab>

- Where to open the specified web page, one of "self" (open in the current window), "window" or "tab" (open in a new window/tab). The default value is "self". Supported since v8.

Browser find  [timeout=<time_interval>]  [elaction=<action>]  [elnumber=<element_number>]  [eltext=<text>]  [elindex=<dropdown_item_index>]  [elvalue=<dropdown_item_value>] [continue=<true|false>]  [<attributes>]

OPTIONS

timeout=<time_value>

- Optional time to keep looking for the element. It must be a valid time value.

• If no timeout is specified the command looks for the element just once.
• If the timeout is specified and is greater than zero the command will keep trying to find the element until the time expires or the element is found.

elaction=<action>

- Optional action to apply to the resulting element. If the search produces multiple elements you may use the elnumber parameter to select the target element. Supported actions are:

• "click" - Click the element. It applies only to clickable elements such as links, buttons etc.
• "type" - Type the text specified by the eltext parameter. Applicable to text elements only.
• "clear" - Clear the element text. Applicable to text elements only.
• "submit" - Submit the form.
• "select" - Select a drop-down item by one of the visible text (eltext), item index (elindex) or its value specified by the "value" attribute of the "option" HTML tag (elvalue).

elnumber=<element_number>

- The ordinal number of the element to target with the action specified by elaction. The default value is 1 (use the first element). If the number of elements is lower than elnumber the command throws an error.

eltext=<text>

- If the elaction action is "type" the parameter specifies the text to type into the text element. If the action is "select" the parameter is used to specify the visible text of the drop-down to be selected. It must be used together with the elaction=type parameter.

elindex=<dropdown_item_index>

- Index of the drop-down item to select. Indexing starts from zero. Applicable only to drop down elements represented by the "select" HTML tag.

elvalue=<dropdown_item_value>

- Value of the drop-down item to be found and selected. It is specified through the "value" attribute of the "option" HTML tag. Applicable only to drop down elements (the "select" HTML tag).

continue=<true|false>

- Specifies how to handle the failure. If the element is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.

<attributes>

- The list of attributes (search criteria) in the form of name=value pairs such as:

• "xpath=<xpath_expression>" - Perform search by the XPath expression. When this option is used no other attribute may be specified.
• "css=<css_selector>" - Search by the CSS selector. When this option is used no other attribute may be specified.
• "id=<element_id>" - Search by the element ID.
• "class=<class(es)>" - A CSS class or a list of space-separated classes the element must be of.
• "tagname=<tag_name>" - An HTML tag name such as "a", "div", "img" etc.
• "text=<text>" - The exact element text.
• "parttext=<partial_text>" - Find element(s) whose text contains the specified partial text. Be aware that the element text is inherited by its parent elements so these criteria are not unique. For example, to get the text of the whole page search for the "HTML" or "body" tag.
• "link=<link_text>" - Search for a link of the specified text.
• "partlink=<partial_link_text>" - Search for a link whose text contains the specified string.
• Besides the parameters supported by Selenium, the command accepts any HTML tag attributes and their values. For example, to identify a form button by its name use name=<name>.

For an informative overview of HTML, attributes see the Mozilla dev docs. Support of attributes may be browser-specific and some of them may fail to recognize.

Browser switch [id=<window_ID>]  [title=<title_or_part>]  [number=<window_number>]  [url=<URL_or_part>]  [continue=<true|false>]

- Switch to the tab or window identified by exactly one of the supported parameters of title, URL, number or window ID. If no identification parameter is specified the command refreshes the window variables.

OPTIONS

id=<window_ID>

- The window/tab ID. It is a unique string assigned to each tab or window by Selenium. You may get the available IDs from the window variables.

title=<title_or_part>

- The window/tab title or its part. See the window variables for the list of available titles. The title search is case sensitive. For example, if you have a tab titled "Google" then you may switch to it using title="Goo". If there are multiple tabs matching the specified title then the first one found will be selected. If no matching tab is found the command terminates the script unless the "continue=true" parameter is specified.

number=<window_number>

- The ordinal number of the window/tab starting with 1 (one). The order of windows is determined by Selenium and it typically reflects the order in which they were created. The number of currently available windows is reflected by the _BROWSER_WINDOW_COUNT window variable. If the number of available windows is lower than the requested one the command terminates the script unless the "continue=true" parameter is specified.

url=<URL_or_part>

- The window/tab URL or its part. See the window variables for the list of available URLs. The search is case sensitive. For example, if you have a tab for "https://www.google.com" then you may switch to it using url="google". If there are multiple tabs matching the specified title then the first one found will be selected. If no matching tab is found the command terminates the script unless the "continue=true" parameter is specified.

continue=<true|false>

- Specifies how to handle the failure. If the target window or tab is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.

Browser close
* Red colour indicates obligatory parameters

OPTIONS

scope=<tab|all>

- The close scope. The value of "all" is default and it will close the whole browser (all tabs & windows) and terminate the Selenium connection. The value of "tab" will close just the current tab or window and the connection is terminated only if it there are no remaining tabs or windows.

EXAMPLES

Browser open browser=edge url=https://www.t-plan.com