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).
  • "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 close" closes the browser and terminates the Selenium session.

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>

* 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.


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 close
* Red colour indicates obligatory parameters

- The "close" operation doesn't accept any parameters.

EXAMPLES

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