Selenium WebDriver Automation With T-Plan

Version 5.0 delivers integration with Selenium WebDriver to enable combined image based and web browser automation from a single script. Features:

The latest version 7.0 integrates with the Selenium Java Client 3.141.59. You may see the version you have in the Browser command preferences (see below). The files are installed to the selenium/ folder and may be eventually replaced manually with a new version.
Supported browsers:
- Microsoft Edge
- Microsoft Internet Explorer
- Firefox
- Chrome
- Safari (Mac OS)
- Chromium embedded browser delivered as a plugin (since 7.0)
Only one local browser can be automated at a time.
Automation of remote browsers (Selenium Grid) is supported since v6.3.

Set Up Instructions

To open a local browser:

Open the Selenium Downloads page and scroll down to the "Third Party Drivers, Bindings, and Plugins" section. Download the target browser driver(s) and extract it to your hard drive.
Select Selenium → Configure Selenium in the Robot menu and set the path(s) to the driver executables.

IMPORTANT: The driver executable version must match the browser one or the connection may fail. For example, to automate Chrome version 101 you need chromedriver.exe version 101. To ensure that the automation is stable disable browser auto update and/or update the driver after every browser update.
Select Selenium → Open Browser... or click the Browser tool bar button. Select the target browser in the drop down and optionally populate the target URL. Click Open to start.

NOTE: Robot v7 introduced the ability to set browser preferences. It is available only for those browser that support this feature through Selenium, namely Firefox and Chrome.

To connect to a remote browser:

Set up the Selenium Grid first.
Select Selenium → Open Browser... or click the Browser tool bar button.
Select the Remote tab in the window, enter the hub URL and select the target browser type. Click Open to start.

Once the browser is up and running you may start to create the script code to drive it. To view elements in the current page open the Selenium → View Elements menu item.

Selenium Configuration

The Browser Command preference screen supports several Selenium configuration options:

You may specify command line arguments to be passed to the Chrome and Firefox drivers. In the case of Chrome it is a way to overcome a number of issues experienced by the community.
There's an option to specify how to handle the system pop ups (alerts). The default behavior is typically DISMISS which makes the driver choose the first option (button) and dismiss the window immediately. To make the alerts stay on the screen set the value to IGNORE.

Automation

There are two new elements in the Robot scripting language:

The "browser" comparison method allows to search for elements in the web page using the standard CompareTo and Waitfor commands.
The "Browser" command allows to manage and drive the Selenium driven browser. For a formal specification of the command see the Language Reference.
- Use "Browser open" to open the target browser and web site. Call "Browser close" to close it.
- Use "Browser find" to locate an element (an HTML tag) in the page and apply an optional action to it (click, type, submit, clear, select). The target element may be identified as follows:
  - FAST: Enter an Xpath, CSS or one or more element attributes and click Verify. If there are multiple elements matching the criteria select the "Choose in viewer" button in the pop up window. Select the target element in the viewer and tick the criteria to identify it.
  - SLOW: Select "Choose in viewer" in the command property window to open the element viewer. As this involves loading of all elements in the current web page it is likely to be slow. Select the target element in the viewer and tick the criteria to identify it.
    
    NOTE: The "Text" and "Partial text" criteria alone is usually not sufficient because Selenium returns the element containing it as well as all its parent elements (div, form, ...). This can be used to retrieve the text of top elements or the whole page. For example, to get all text in the page set the "Tag Name" to "body". The calling script may then retrieve the text from the _WEB_TEXT variable.
- Once you design the criteria you may select the Perform Action button to apply the selected action to the target element. This allows you to avoid direct interaction with the browser and to verify that it works as expected.
- Select OK to save the command to the active script editor. If you wish to design another "Browser find" command on the next line click "OK & Create New" button instead.

The "Browser find" command exposes the number of elements found and some of their attributes through a set of variables:

Variable Name	Description
_WEB_COUNT=<number>	The number of elements retrieved by "Browser find"
_WEB_X_<n>=<x-coordinate> _WEB_Y_<n>=<x-coordinate> _WEB_W_<n>=<x-coordinate> _WEB_H_<n>=<x-coordinate>	The X and Y coordinates, width and height of the n-th element.
_WEB_TEXT=<text>	Text of the n-th element (cumulative/including texts of all child elements).

The command in addition stores HTML attributes of the first up to 30 elements to the _WEB_ prefixed variables. For example, when looking for a link (the "a" tag) the "href" attribute of the second element will be available as the _WEB_HREF_2 variable. The limit of 30 elements is applied for performance reasons and can not be changed.

Automation Example

Let's demonstrate Robot capabilities on a simple example:

Open the Wikipedia home page in Firefox
Type 'automation' into the search field and submit it to open the Automation topic.

A pure Selenium solution in Java would look like:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.firefox.FirefoxDriver; import org.openqa.selenium.By;

public class WikipediaAutomation {

    public static void main(String args[]) {
        // Set path to the Firefox/Gecko driver
        System.setProperty("webdriver.gecko.driver", "C:\\Selenium\\geckodriver.exe");

        // Create the driver and execute the script
        WebDriver driver = new FirefoxDriver();
        // Open the Wikipedia home page
        driver.get("https://www.wikipedia.org");

        WikipediaAutomation script = new WikipediaAutomation();
        script.automate(driver);
    }

    public void automate(WebDriver driver) {
        // Enter 'automation' into the search field
        driver.findElement(By.id("searchInput")).sendKeys("automation");

        // Submit the form using the button next to the field
        driver.findElement(By.xpath("//button")).submit();
    }
}

To design the same script in Robot use the Browser open and Browser find property windows described in the previous chapter.

If your script is a TPR one the corresponding code will look like:

Browser "open" browser="firefox" url="https://www.wikipedia.org"
Browser "find" id="searchInput" elaction="type" eltext="automation"
Browser "find" tagname="button" elaction="submit"

If your script is a Java one the property windows will generate an automation code similar to the one below. The rest of the Java script class is omitted for brevity.

browserOpen("firefox", "https://www.wikipedia.org");
browserFindAndType("automation", "id", "searchInput");
browserFindAndSubmit("tagname", "button");

Selenium API Access

Robot does not support all the Selenium functionality yet. You may reach an unsupported Selenium feature at the level of the Java code from a Robot Java test script as follows:

WebDriverAdapter adapter = WebDriverAdapterFactory.getInstance().getAdapter(getContext(), WebDriverAdapter.ADAPTER_NAME_SELENIUM);

org.openqa.selenium.WebDriver driver = (org.openqa.selenium.WebDriver) adapter.getDriver();

For example, to accept and dispose a JavaScript pop up from a TPR test script use the following Java code block:

java {
   import com.tplan.robot.remoteclient.webdriver.WebDriverAdapter;
   import com.tplan.robot.remoteclient.webdriver.WebDriverAdapterFactory;

   WebDriverAdapter adapter = WebDriverAdapterFactory.getInstance().getAdapter(getContext(), WebDriverAdapter.ADAPTER_NAME_SELENIUM);
   org.openqa.selenium.WebDriver driver = (org.openqa.selenium.WebDriver) adapter.getDriver();
   driver.switchTo().alert().accept();
} endjava

Integration of Existing Selenium Scripts

Existing Selenium Java code may be freely combined with Robot scripts. The only thing the two entities must share is the Selenium web driver object (the org.openqa.selenium.WebDriver instance). The key class in the Robot framework is com.tplan.robot.remoteclient.webdriver.WebDriverAdapterFactory which allows to access the driver wrapper class (WebDriverAdapter) assigned to the executing scripts.

For example, to let Robot open the Wikipedia home page in Firefox and then perform the automation using our pure Selenium example above create a Robot Java script as follows:

package test; import com.tplan.robot.scripting.*;
import com.tplan.robot.*;
import com.tplan.robot.remoteclient.webdriver.*;
import java.io.*;

public class RobotWikipediaScript extends DefaultJavaTestScript {

    public void test() {
        try {
            // Call "Browser open" to create the driver
            browserOpen("firefox", "https://www.wikipedia.org");

            // Obtain a reference to the Selenium driver from the Robot framework
            WebDriverAdapter adapter = WebDriverAdapterFactory.getInstance().getAdapter(getContext(), WebDriverAdapter.ADAPTER_NAME_SELENIUM);
            org.openqa.selenium.WebDriver driver = (org.openqa.selenium.WebDriver) adapter.getDriver();

            // Call the existing example Selenium script
            WikipediaAutomation seleniumScript = new WikipediaAutomation();
            seleniumScript.automate(driver);

        } catch (StopRequestException ex) {
            throw ex;
        } catch (IOException ex) {
            ex.printStackTrace();
            throw new IllegalStateException(ex);
        }
    }

    public static void main(String args[]) {
        RobotWikipediaScript script = new RobotWikipediaScript();
        ApplicationSupport robot = new ApplicationSupport();
        AutomatedRunnable runnable = robot.createAutomatedRunnable(script, "RobotWikipediaScript@" + Integer.toHexString(script.hashCode()), args, System.out, false);
        new Thread(runnable).start();
    }
}

It is not possible to call existing Selenium scripts from TPR ones directly. You must wrap the Selenium execution into a Robot Java script and then call it using the Run command.

For example, to drive our automation from a TPR script remove the "browserOpen("firefox", "https://www.wikipedia.org")" method call from the RobotWikipediaScript example above and call it from TPR as:

Browser "open" browser="firefox" url="https://www.wikipedia.org"
Run "test.RobotWikipediaScript"

To make the above example work please put the compiled Selenium code (a JAR or a class path with the compiled WikipediaAutomation class) onto the Robot class path.