Selenium WebDriver Plugin/en
- 1 Introduction
- 2 Browser Support
- 3 Additional Uses
- 4 Quick Start
- 5 Connecting
- 6 Plugin Settings
- 7 Recorder
- 8 Authentication Alerts
- 9 Transferring Old Selenium Tests
- 10 FAQ
Use the Selenium WebDriver Plugin to test or automate interactions of applications running in a web-browser (*). The plugin can be (and usually is) used with the GUI Browser, which helps in the creation of tests. Moreover, the GUI Browser can record UI sessions, which can later be customised or refactored as required.
The Selenium WebDriver Plugin replaces the previous Selenium Web Test Plugin, which was based on the now outdated Selenium RC framework.
The new web driver uses the Selenium WebDriver for automation, and replaces the previous interface. (see https://www.guru99.com/introduction-webdriver-comparison-selenium-rc.html for background information and a description of the differences.) Read this section for information how to transfer testsuites using the old plugin.
(*) actually, there exists WebDriver interfaces to control Windows or OS X desktop applications. Thus, this plugin can be used in a number of additional scenarios.
This plugin supports (among others) the Chrome/Chromium, Edge, Firefox, Internet Explorer and Opera browsers.
Safari under OSX must be at least version 10, and OSX must be at least El Capitan. The plugin uses the WebDriver interface for communication; therefore, browsers running both on the local or on a remote machine can be tested and/or controlled. In addition, many other browsers, UIs and devices support the WebDriver protocol, and can thus be automated/tested with expecco.
Each browser has a driver ("WebDriver") for opening and controlling a browser window. Usually, the driver is a separate program which translates WebDriver requests into browser-specific interface calls. However, there are also browsers and programs which have the WebDriver protocol already built in (eg. Safari).
The expecco installation package includes drivers for common browsers. However, you may have to update a driver, if the browser version changes. The used drivers are located in your expecco installation directory below the installation folder in:
(of course, with "\”s instead of "/"s on Microsoft Windows operating systems). To use a different driver, check the "Advanced" toggle in the connection dialog and add the driver's path to the settings (see below).
In some cases, expecco may show a warning, that the driver version might be incompatible with the browser. This does not mean per se, that the combination does not work; instead, it means that the combination has not been tested by eXept, but may nevertheless work. If such a warning is shown, check the "Do not show this warning again" toggle, to have expecco remember that combination as "trusted" in your settings.
You find new driver versions at the following addresses:
Download a suitable version and place it at an appropriate location in the above mentioned directory. expecco will then find and use it. Alternatively, you can set the path to a driver either in the connection editor or in the plugin settings.
Please verify that the driver's version is compatible with the browser version. If in doubt, consult the version history (e.g. for Chrome: https://chromedriver.storage.googleapis.com/2.25/notes.txt).
Notice: For Internet Explorer, "
Protected Mode" settings must be set to the same value for all zones, to be able to start a connection. (in the Internet Explorer, open "Settings" - "Internet Options" - "Security", and set the value of "protected mode" to the same in all 4 zones; otherwise, you'll get error- and warning dialogs when connecting). See also the required configuration to use InternetExplorerDriver.
If you get an error like
|AppiumForMac||WebDriver to control OS X apps (i.e. also non-Browsers)|
|WinAppDriver||WebDriver to control Windows Desktops|
Notice, that these interfaces usually provide a subset of the functionality provided by special plugins, such as Java-GUI or WindowsAutomation plugins. Usually, they are ok to manipulate the top level window or to confirm simple dialogs, but less usable for more complex UI tests.
Open Browser / Connecting
- Start expecco
- Click on "New Testsuite"
- Click on the GUI-Browser symbol ()
- A new Tab appears, containing the GUI-Browser
- Click on "Connect" and choose "Selenium Testing". The Connection Dialog appears (see details below)
- Choose the type of browser (eg. "
firefox" and enter the URL of the tested web site (eg. "
http://www.myHost.com") and )
- Click on "Connect"
- A browser is started automatically, and the page is shown
- As soon as the connection is established, the page's elements are shown in the GUIBrowser's left tree view
Start a Recording
- Select an element in the browser's element-tree, or move the mouse over it in "follow-mouse mode". If your browser does not support this "follow-mouse" mode, try opening a recorder, and move the mouse there.
The element's attributes are shown in the lower-center attribute/property list.
Manually adding Actions and Checks
- In addition to recording, actions and checks can also be selected from the upper-centre action list. Select one there and either try it immediately or add it to the recording sequence via the add-action button at the top far right.
The connection editor defines, changes or starts a connection. Open the GUI browser, click on "Connect" and select "Selenium Testing (WebDriver)". You can also create attachments or files containing connection parameters ("connection settings") without actually connecting to/opening a new browser connection via the "Save Connection Settings" menu item.
When opened, the connection editor presents a number of fields and load/save buttons in its toolbar menu:
- Load settings from attachment: Open an attachment containing connection settings from an open project. This settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
- Load settings from file: Open a saved settings file (*.csf). Its settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
- Save settings as attachment: Save all entered settings as attachment in an open project.
- Save settings as JSON attachment: Save all entered settings in JSON format as attachment in an open project.
- Save settings to file: Save all entered settings to a file (*.csf).
- Version info: Opens a window showing the used versions of the Selenium server, the selected browser and its driver.
- Online documentation: Open this online documentation page.
- Connection name: Enter the name of the connection used to show it in the GUI browser. (Optional)
- Browser type: Choose the type of browser to use. Ensure it is installed and the version of the used driver is compatible with the browser version.
- URL: Enter the URL to open at startup. To open an empty browser window, leave this field empty. To open a local file use the "
file://" scheme, e.g. "
- Advanced view: Toggle the view to enter advanced settings.
- Information on the selected browser: Here, the selected browser type is shortly characterized.
- Information on the settings: It shows which Selenium, browser and driver version will be used regarding the current settings. If you have set advanced settings, they will also be displayed here.
Besides the used browser and the start URL, more settings and possibly "capabilities" may be required. To see click on the "Advanced" toggle. Depending on the selected browser type you get different entry fields.
- Remote Server: To open a browser on a remote host, start a Selenium server there and set this field to its address. You can also enter a local address if you do not want the Selenium server to start automatically or if it is already running. See the next section Remote Connections on how to start a Selenium server.
- Headless: to open the browser in "headless" mode, i.e. without a window. Not all browsers/drivers support this mode.
- Binary: Enter the path to the binary of the selected browser. Use this if the browser cannot be found automatically by Selenium, or if you have another browser version installed or to be tested against.
- Driver: For each browser, a particular driver is needed for automation. New browser versions often also need a new driver version. If you don't want or cannot use the driver provided by expecco, set its path here.
- Command Line Options: arguments passed to the browser-command. For example the chrome browser supports a "--disable-extensions" command line argument, firefox supports "--safe-mode" and "--profile". These options are browser- and possibly browser-version specific. Most browsers allow for a "--help" argument, which you may try in a shell window to find out.
- Firefox Profile: For Firefox, it is possible to set a Firefox Profile, containing specific settings. If no profile is set, each connection will use a new empty one.
- Capabilities: Selenium connections can use several capabilities to define the connection's behavior. To add specific capabilities, set them in this field. Write "<capability name>: <value>" or "<capability name> = <value>", one entry per line.
The set of capabilities needed or supported are browser- and driver specific. Please refer to the concrete driver's documentation as found via the driver links above. Common capabilities are: "app" or "application", "url", etc. For drivers which communicate with mobile devices, the capabilities also select which device to use and/or wether an emulator should be started.
You can also set properties for the Firefox browser - for this, use the same syntax as for capabilities, but add a leading $ to the property name.Properties used by expecco internally (such as browser type, url or remote host) are prefixed by a "#"-character.
To start a browser on a remote computer, copy the Selenium server and the required driver to that computer. You find the files in your expecco installation at "
packages\exept\expecco\plugin\seleniumWebDriver\lib". Start the Selenium server (on the remote host) with:
java -jar selenium-server-standalone-3.6.0.jar
By default, the server will listen on port 4444. To use another port, set it with the "
-port <nr>" command line argument. To connect to that server, set the "remote server" parameter of the connection to "<Server-Address>:4444/wd/hub".
Check and possibly configure your firewall to allow transmission through the port.
"Headless Browsing" means: "without a window", and is useful to test web-pages for reachability, performance and structure. You can either use the HTMLUnit browser type, which simulates a browser, or run against one of the real browsers in headless mode. Notice, that not all browsers support this headless mode - we recommend using "firefox" or "chrome" for this.
Also notice, that in order to verify that a web page's interaction with a browser works correctly, you should test against real browsers. For an introduction on what "headless browsing" means, see for example https://www.guru99.com/selenium-with-htmlunit-driver-phantomjs.html.
Notice: the HTMLUnit driver has been removed from the latest selenium distribution and is also no longer supplied with expecco (it was not a good test tool anyway, as it behaved differently from real browsers).
If required, download from https://github.com/SeleniumHQ/htmlunit-driver.
SeleniumWebDriverLibrary offers a number of blocks to start a Selenium connection within a testrun. The connection name identifies the connection during the run, if the test uses multiple connections and switches between them (eg. if multiple browser windows are open simultaneously). To start a connection with predefined settings, save them in the connection dialog (as attachment), and use the "[Connect From File]" action block.
To use certain browser installations or drivers as default, for every connection, set them in the settings dialog of the plugin ("Extras" → "Settings" → "Plugins" → "Selenium WebDriver Extension"). Settings for specific browsers can be found under "Most Popular Browsers" or "Other Browsers". The settings there are used as default, unless overwritten by an individual connection configuration.
Execution Delay for Chrome
The following description applies to all GUI technologies which support remote recording in the integrated expecco recorder: the behaviour of the recorder is (apart from small differences due to technology-specific limitations) the same across different connections.
Use of this recorder has some advantages over direct recording in the browser:
- it can be used with remote machines/connections/mobil devices
especially for mobile devices, which may be all located in a separate (server-) room
- it provides precise control over which event is to be recorded.
Once connected to a browser, the integrated recorder can be used to record a test case. Start the recorder by selecting the appropriate connection in the GUI browser's left tree and click the record button. The recorder opens a new window. Each click in the window records an action. More actions are available in the menu. Recorded actions are added to the workspace of the GUI browser to form a sequence of interactions. This sequence can be edited, parametrized or replayed immediately. When finished, it should be saved into the suite as a new "Test Action".
General actions can be found either directly in the menu bar or there in the Browser Tools menu (see below). To record actions on elements, either change the selection of the element tool in the menu bar (see below) and click on the element or select the corresponding action from the context menu by right-clicking on the element. For text input, you can also place the cursor over the element and enter the text. The input dialog for this action opens. It is also possible to record the imputs backspace, return and tab that way.
Components of the recorder window
- Pause recording: If the control lamp is red, the recorder is in "recording"-mode. Pause the recording by clicking on this lamp. The lamp will turn to grey. In this state you can execute actions with the recorder, but they are not recorded. Click again to resume the recording.
- Update: Update the screenshot on the element tree. Necessary if the recorder view does not fit the browser content.
- Follow-Mouse: The element under the cursor is selected in the GUI browser.
- Element Highlighting: The element under the cursor gets a red frame.
- Element Tools: Select which tool to use for recording. You can choose between all actions that use a certain element. The selected action is triggered by each click in the view and the element is determined by the click position. Not selected actions are available by right click.
- Browser Tools: Actions not refering to ocertain elements, like scrolling or actions on the current URL or the title, can be triggered here.
- Page navigation: Actions for page navigation: Back, Forward and Refresh Page
- Alert Handling: Click this button if the browser shows an alert, to be able to select the actions for alert handling.
- Online Documentation: Open this online documentation.
- View: Shows a screenshot of the browsers. Actions can be triggered by mouse depending on the selected tool. If a new action can be entered, the frame of the window is green, red otherwise. Scrolling is forwarded to the browser, but not recorded.
- Resize Window to Screen Size: Change the size of the window to show the whole screenshot.
- Set Screen Scale to Fit Window: Scale the screenshot to fully fit in the window
- Scale: Changes the scale of the screenshot. Can also be adjusted by scrolling with pressed CTRL key.
- Notifications: Shows notifications, e.g. if an action cannot be recorded. The last notification is displayed until it is closed by the button on its right side.
If a Web page uses HTTP authentication with Basic Authentication, an alert window for entering the user name and password opens when the page is loaded. This window cannot be accessed directly with Selenium. In the GUI browser, it is displayed as an alert. An exception to this is Chrome, where the driver does not respond to any request as long as the dialog is open. At this point, the plugin cannot even determine whether an authentication dialog is open or whether the driver is not responding for other reasons.
For local connections under Windows, authentication can be performed using Windows Access. In the SeleniumWebDriverLibrary there are specific authentication blocks for individual browser types as well as the block Authenticate at Alert, which executes the corresponding block depending on the connection. There are different restrictions for the different browser types:
- Chrome: The credentials are sent to a chrome window, so it only works if not more than one are open. In this case, the single block has the option to specify the title of the window.
- Edge: With Microsoft Edge a login is not supported.
- Firefox: Sends the credentials to a Firefox dialog box and therefore only works if there are not multiple ones.
- Internet Explorer: With Internet Explorer a login is not supported.
As an additional option, you can also log in using the URL. Instead of the page https://www.example.com call the URL https://user:email@example.com. It is important that : and @ do not appear in the user name or password. This method may not be supported by every browser.
With the WindowsAutomation2-Plugin it is also possible to execute such a login with all browser types.
Transferring Old Selenium Tests
This Plugin replaces the previous Selenium Web Test Plugin, which is based on Selenium RC. Selenium RC is no longer supported by their authors and it will also no longer be maintained by exept. The successor is Selenium WebDriver, also referred to as Selenium 2.
Tests which were created with the old Selenium WebTest Plugin using SeleniumLibrary can be executed with the new Selenium WebDriver. For this, go to the plugin settings of "Webtest Legacy (Selenium)" and check "Use WebDriver for execution". Please verify that your tests are still running after this change, as there is no 100% backward compatibility (which is outside the scope of expecco). However, most of the old test actions should run without problems.
- Scrollbars cannot be handled in the recorder
- The scrollbar of the browser which is diplayed if a page is larger than the browser window is no controllable web element. Mostly it is useless to scroll by a certain amount in a test where the size of the browser window is not defined. Instead, use the block
[Web] Scroll Element into Viewto scroll a relevant element to the visible region. The default click block used by the recorder already includes this action (
[WebElement] Click (Scroll Element into View)). If you scroll on the recorder window, the action will also be applied to the browser, but is not recorded. If you actually want to scroll by a certain amount, there is an appropriate entry in the browser actions, and more blocks in the SeleniumWebDriverLibrary.
- Block fails if element becomes visible too late
- All blocks that use an element path have built in that they wait until a corresponding element appears. However, there are cases where an element is already there, but not yet visible. If you click on the element you will get an error. Possible errors in this context are
org.openqa.selenium.ElementNotInteractableException: element not interactableand
[Web] Wait for Visibility of Elementblock or
[Web] Wait for Element to Be Clickablebefore interacting with the element.
- Error message
Cannot read property 'left' of undefined
- The error
[Web] Selectblock with the <select> element.
- Block runs successfully, but without effect
- This case can occur with Chrome. The element is available, the action does not throw an error, but nothing is executed. Usually it helps to wait briefly before the execution, see Execution Delay for Chrome.
- Executions using Chrome are slower
- To fix a problem when executing with Chrome, a delay is defined in the plugin settings for Chrome. Check if this value is possibly too high; see Execution Delay for Chrome.