Repository files navigation

SeleniumLibrary is a web testing library forRobot Framework thatutilizes theSelenium tool internally. The project is hosted onGitHuband downloads can be found fromPyPI.

SeleniumLibrary works with Selenium 3. It supports Python 2.7 as well asPython 3.4 or newer. In addition to the normalPython interpreter, itworks also withPyPy andJython. UnfortunatelySelenium is notcurrently supported byIronPython and thus this library does not work withIronPython either.

SeleniumLibrary is based on theold SeleniumLibrary that was forked toSelenium2Library and then later renamed back to SeleniumLibrary.See theVersions andHistory sections below for more information aboutdifferent versions and the overall project history.

Seekeyword documentation for available keywords and more informationabout the library in general.

The recommended installation method is usingpip:

pip install --upgrade robotframework-seleniumlibrary

Running this command installs also the latest Selenium and Robot Frameworkversions, but you still need to installbrowser drivers separately.The--upgrade option can be omitted when installing the library for thefirst time.

Those migrating fromSelenium2Library can install SeleniumLibrary so thatit is exposed also as Selenium2Library:

pip install --upgrade robotframework-selenium2library

The above command installs the normal SeleniumLibrary as well as a newSelenium2Library version that is just a thin wrapper to SeleniumLibrary.That allows importing Selenium2Library in tests while migrating toSeleniumLibrary.

To install the last legacySelenium2Library version, use this command instead:

pip install robotframework-selenium2library==1.8.0

With resent versions ofpip it is possible to install directly from theGitHub repository. To install latest source from the master branch, usethis command:

pip install git+https://github.com/robotframework/SeleniumLibrary.git

Please note that installation will take some time, becausepip willclone theSeleniumLibrary project to a temporary directory and thenperform the installation.

SeeRobot Framework installation instructions for detailed informationabout installing Python and Robot Framework itself. For more details aboutusingpip seeits own documentation.

After installing the library, you still need to install browser andoperating system specific browser drivers for all those browsers youwant to use in tests. These are the exact same drivers you need to use withSelenium also when not using SeleniumLibrary. More information aboutdrivers can be found fromSelenium documentation.

The general approach to install a browser driver is downloading a rightdriver, such aschromedriver for Chrome, and placing it intoa directory that is inPATH. Drivers for different browserscan be found via Selenium documentation or by using your favoritesearch engine with a search term likeselenium chrome browser driver.New browser driver versions are released to support features innew browsers, fix bug, or otherwise, and you need to keep an eye on themto know when to update drivers you use.

Alternatively, you can use a tool calledWebdriverManager which canfind the latest version or when required, any version of appropriatewebdrivers for you and then download and link/copy it into rightlocation. Tool can run on all major operating systems and supportsdownloading of Chrome, Firefox, Opera & Edge webdrivers.

Here's an example:

pip install webdrivermanagerwebdrivermanager firefox chrome --linkpath /usr/local/bin

To use SeleniumLibrary in Robot Framework tests, the library needs tofirst be imported using theLibrary setting as any other library.The library accepts some import time arguments, which are documentedin thekeyword documentation along with all the keywords providedby the library.

When using Robot Framework, it is generally recommended to write aseasy-to-understand tests as possible. The keywords provided bySeleniumLibrary are pretty low level, though, and often requireimplementation specific arguments like element locators to be passedas arguments. It is thus typically a good idea to write tests usingRobot Framework's higher level keywords that utilize SeleniumLibrarykeywords internally. This is illustrated by the following examplewhere SeleniumLibrary keywords likeInput Text are primarilyused by higher level keywords likeInput Username.

*** Settings ***Documentation     Simple example using SeleniumLibrary.Library           SeleniumLibrary*** Variables ***${LOGIN URL}      http://localhost:7272${BROWSER}        Chrome*** Test Cases ***Valid Login    Open Browser To Login Page    Input Username    demo    Input Password    mode    Submit Credentials    Welcome Page Should Be Open[Teardown]    Close Browser*** Keywords ***Open Browser To Login Page    Open Browser${LOGIN URL}${BROWSER}    Title Should Be    Login PageInput Username[Arguments]${username}    Input Text    username_field${username}Input Password[Arguments]${password}    Input Text    password_field${password}Submit Credentials    Click Button    login_buttonWelcome Page Should Be Open    Title Should Be    Welcome Page

The above example is a slightly modified version of an example in ademo project that illustrates using Robot Framework and SeleniumLibrary.See the demo for more examples that you can also execute on your ownmachine. For more information about Robot Framework test data syntax ingeneral see theRobot Framework User Guide.

Before creating your own library which extends theSeleniumLibrary, please consider wouldthe extension be also useful also for general usage. If it could be useful also for generalusage, please create a new issue describing the enhancement request and even better if theissue is backed up by a pull request.

If the enhancement is not generally useful, example solution is domain specific, then theSeleniumLibrary offers a public API's which can be used to build own plugins and libraries.Plugin API allows to add new keywords, modify existing keywords and modify internalfunctionality of the library. Also new libraries can be build on top of theSeleniumLibrary. Please seeextending documentation for more details about theavailable methods and for examples how the library can be extended.

If the provided documentation is not enough, there are various support forumsavailable:

• robotframework-users mailing list
• #seleniumlibrary and#seleniumlibrary-dev channels inRobot FrameworkSlack community
• SeleniumLibraryissue tracker for bug reports and concrete enhancementrequests
• Other support forums including paid support

SeleniumLibrary has over the years lived under SeleniumLibrary andSelenium2Library names and different library versions have supporteddifferent Selenium and Python versions. This is summarized in the tablebelow and theHistory section afterwards explains the project historya bit more.

SeleniumLibrary originally used the Selenium Remote Controller (RC) API.When Selenium 2 was introduced with the new but backwards incompatibleWebDriver API, SeleniumLibrary kept using Selenium RC and separateSelenium2Library using WebDriver was forked. These projects containedmostly the same keywords and in most cases Selenium2Library was a drop-inreplacement for SeleniumLibrary.

Over the years development of the old SeleniumLibrary stopped and alsothe Selenium RC API it used was deprecated. Selenium2Library was developedfurther and replaced the old library as the de facto web testing libraryfor Robot Framework.

When Selenium 3 was released in 2016, it was otherwise backwards compatiblewith Selenium 2, but the deprecated Selenium RC API was removed. This had twoimportant effects:

• The old SeleniumLibrary could not anymore be used with new Selenium versions.This project was pretty much dead.
• Selenium2Library was badly named as it supported Selenium 3 just fine.This project needed a new name.

At the same time when Selenium 3 was released, Selenium2Library was goingthrough larger architecture changes in order to ease future maintenance andto make adding Python 3 support easier. With all these big internal andexternal changes, it made sense to rename Selenium2Library back toSeleniumLibrary. This decision basically meant following changes:

• Create separate repository for theold SeleniumLibrary to preserveits history since Selenium2Library was forked.
• Rename Selenium2Library project and the library itself toSeleniumLibrary.
• Add newSelenium2Library project to ease transitioning from Selenium2Libraryto SeleniumLibrary.

Going forward, all new development will happen in the new SeleniumLibraryproject.