SeleniumLibrary is a web testing library for Robot Framework that utilizes the Selenium tool internally. SeleniumLibrary 3.0.0 is a new release with Python 3 support and various other big enhancements such as better public API for extending the library and highly enhanced keyword documentation. The library architecture has also changed making it easier to maintain and develop further.
If you have pip installed, just run
pip install --upgrade robotframework-seleniumlibrary
to install the latest available release or use
pip install robotframework-seleniumlibrary==3.0.0
to install exactly this version. Alternatively you can download the source distribution from PyPI and install it manually.
SeleniumLibrary 3.0.0 was released on Friday December 1, 2017.
- Most important enhancements
- Backwards incompatible changes and deprecated features
- Robot Framework and Selenium minimum versions increased
- New architecture
- Attributes in programmatic API renamed
- Keywords returning lists don't fail if there are no matches
Set Screenshot Directorydoes not automatically restore old value- Changes to locating windows
- Deprecated keywords
- Other backwards incompatible changes
- Acknowledgements
- Full list of fixes and enhancements
SeleniumLibrary was enhanced to support Python 3 (#479) and at the same time Python 2.6 support was dropped (#620). More precisely, the currently supported Python versions are 2.7, 3.3 and newer.
Because Selenium moved from version 2 to version 3, we felt that the old name, Selenium2Library, did not anymore describe what the library supports and helps user to achieve. At the same time the old SeleniumLibrary became totally unusable as Selenium 3 dropped support for the remote controller API it used.
In this situation we decided to rename Selenium2Library to SeleniumLibrary (#777). We also created new Selenium2Library that is just a wrapper for SeleniumLibrary and is meant only to ease migration. For more information see the project pages.
The general project documentation (#873) as well as keyword documentation (#924 and #925) have been enhanced heavily and in practice rewritten.
The old architecture did not work too well anymore when the library had grown so large and it made the development of the library slower or more difficult. The old architecture also made it hard to define clear API for the user who are building their own libraries on top of the SeleniumLibrary.
The new architecture (#771) relies on the Robot Framework Dynamic library API, PythonLibCore and using context object to share state and common methods between different classes and methods. Because of the new architecture, many private methods or classes have been changed or removed totally.
The new architecture should not change how the keywords are used in Robot Framework test data. But new architecture causes changes how the SeleniumLibrary can be used to build new libraries. We have deprecated many private methods and have created many new public methods or attributes which should make the extending more easier in the future. The public API is also documented (#882).
Nowadays the recommended syntax to specify an explicit locator strategy
is strategy:value like id:example or css:h1 (#908). The old (and
still supported) strategy=value syntax is problematic because Robot
Framework uses the same syntax with named arguments.
In the previous releases, the table keywords locator strategy did differ greatly from the rest of keywords which did interact with elements in the browsers. This is now changed and tables can be located with same locator strategies which can be used for the rest of the library (#923).
The logic of alert related keywords has been rewritten. The alert keywords logic in previous releases was not clear and contained many obvious bugs. Because of this many of the alert keywords has been deprecated and new keywords have been created to provide better interface for handling alters. See the keyword documentation and the issue #933 for details about the change.
In addition to the standard Python 2 and Python 3 interpreters, also Jython and PyPy are now officially supported (#879).
Nowadays the minimum supported Robot Framework version is 2.8.7 (#703). It is likely that SeleniumLibrary 3.1 raises this requirement to Robot Framework 2.9 or even 3.0.
The minimum required Selenium version is now 2.53.6.
The better architecture discussed above changes library internals a lot. This should not affect tests using keywords provided by the library, but other libraries and tools interacting with SeleniumLibrary are likely to require an update.
How to interact with the library and how to safely extend it is going to be documented. Until that, if you are a maintainer of a library that is broken due to these changes, please report your problems on robotframework-users mailing list, or on #seleniumlibrary channel on the Slack community.
Various attributes in the programmatic API have been renamed and the old attribute names are deprecated (#882).
Earlier Get WebElememts (#805) and Get Selected List Values/Labels
keywords (#977) failed if where were no matches. Nowadays they return
an empty list instead.
Earlier Set Screenshot Directory keyword tried to automatically restore
the previous value when the current scope end, but this functionality was
not documented adequately and contained bugs. The functionality was removed
and, instead, the keyword returns the previous value similarly as Set
Selenium Timeout and other Set ... keywords.
Locating windows has been cleaned up and documented thoroughly. As part of the cleanup, undocumented features not considered useful were deprecated or removed:
- Using Python
Noneor stringnullor empty string as a locator to select the main window is deprecated. Use documentedmain(default) instead. - Using
popupto select the latest new window is deprecated. Use documentednewinstead. - Using
selfto select the current window is deprecated. Use earlier undocumented but much more explicitcurrentinstead. - Locating windows by name, title or URL is not case-insensitive anymore.
- Specifying explicit locator strategy is not case-insensitive anymore.
Such changes are obviously backwards incompatible, but because these are undocumented features, it's very unlikely that they are used widely.
Various hard-to-use or badly named keywords have been "silently" deprecated in favor of better keywords. This means that the old keywords can be still used without warnings, but they will emit a deprecation warning staring from SeleniumLibrary 3.1.
| Deprecated keyword | Use instead | Issue |
|---|---|---|
| Select From List | Select From List By Label/Value/Index | #988 |
| Unselect From List | Unselect From List By Label/Value/Index | #988 |
| Current Frame Contains | Current Frame Should Contain | #920 |
| Get Cookie Value | Get Cookie | #932 |
| List Windows | Get Window Handles | #966 |
| Locator Should Match X Times | Page Should Contain Element (w/ limit argument) |
#949 |
| XPath Should Match X Times | Page Should Contain Element (w/ limit argument) |
#949 |
| Get Matching XPath Count | Get Element Count | #949 |
| Focus | Set Focus To Element | #920 |
| Simulate | Simulate Event | #920 |
| Input Text Into Prompt | Input Text Into Alert | #933 |
| Choose Ok On Next Confirmation | Handle Alert | #933 |
| Choose Cancel On Next Confirmation | Handle Alert | #933 |
| Confirm Action | Handle Alert | #933 |
| Get Alert Message | Handle Alert | #933 |
| Dismiss Alert | Handle Alert | #933 |
- Bundled Firefox profile has been removed and Selenium default profile is used instead (#883).
Register Keyword To Run On Failurereturns PythonNone, not stringNo keyword, if no keywords was previously registered (#176).Capture Page Screenshotdoesn't overwrite existing screenshots by default (#502).- Checkbox keywords don't anymore work with radio buttons (#962)
Wait Until Element Is Enabledchecks alsoreadonlystatus (#958)- It is an error to unregister a locator strategy that hasn't been registered (#961).
Many thanks to "thaffenden" to add Get Locations keyword. "davidshepherd7" to fixing issue
when getting window information and switching windows on browsers that do not support javascript.
Many thanks to "wappowers" who added 'Get Cookie' keyword and added 'expiry' as value that can be set with 'Add Cookie' keyword.
Many thanks to many other contributors who have helped to make this release.
| ID | Type | Priority | Summary |
|---|---|---|---|
| #479 | enhancement | critical | Python 3 support |
| #777 | enhancement | critical | Change library name from Selenium2Library to SeleniumLibrary |
| #620 | enhancement | high | Drop Python 2.6 support |
| #771 | enhancement | high | Create better architecture |
| #873 | enhancement | high | Enhance project documentation in README |
| #879 | enhancement | high | Document that Jython and PyPy are supported but IronPython is not |
| #882 | enhancement | high | Externally useful attributes should be declared public and documented. |
| #908 | enhancement | high | New strategy:value syntax to specify locator strategy in addition to current strategy=value |
| #923 | enhancement | high | Tables should be located using same logic as other elements |
| #924 | enhancement | high | Enhance general library documentation in keyword docs |
| #925 | enhancement | high | Cleanup and enhance keyword documentation |
| #933 | enhancement | high | Clean up keywords related to alerts |
| #176 | bug | medium | Return value of Register keyword to run on failure cannot always be used to restore original state |
| #435 | bug | medium | Note version added to recently added keywords. |
| #546 | bug | medium | HTML5 specialized text fields not recognized as text fields |
| #652 | bug | medium | Handling alerts sometimes fails with Chrome |
| #779 | bug | medium | Acceptance test do not work in windows |
| #790 | bug | medium | Cannot switch windows on browsers which don't support javascript |
| #816 | bug | medium | Modify Capture Page Screenshot keyword not fail if browser is not open. |
| #891 | bug | medium | Fix setting cookie expiry date |
| #990 | bug | medium | Bugs finding table cells when row has both td and th elements |
| #502 | enhancement | medium | Capture Page Screenshot should not overwrite if file already exist |
| #673 | enhancement | medium | Support locating elements using element class |
| #703 | enhancement | medium | Update required Robot Framework version to 2.8 |
| #704 | enhancement | medium | Increase the required selenium version to latest selenium 2 version |
| #719 | enhancement | medium | Use booleans arguments like in Robot Framework |
| #722 | enhancement | medium | Enhance Get List Items to support returning values or labels |
| #805 | enhancement | medium | Modify Get Webelements not to raise exception when no elements are found |
| #851 | enhancement | medium | Add keyword that checks focus |
| #883 | enhancement | medium | Remove SeleniumLibrary profile for Firefox |
| #932 | enhancement | medium | Add keyword to get all cookie information |
| #942 | enhancement | medium | Support configurable timeout with alert related keywords |
| #966 | enhancement | medium | Cleaning up locating windows |
| #977 | enhancement | medium | Get Selected List Values/Labels keywords should not fail if list has no selections |
| #987 | enhancement | medium | New Unselect All From List keyword |
| #988 | enhancement | medium | Deprecate Select From List and Unselect From List |
| #592 | bug | low | Deprecation warning from Selenium when using Select/Unselect Frame |
| #759 | bug | low | Change link in help Get Alert Message to Dismiss Alert |
| #962 | bug | low | Some checkbox keywords work also with radio buttons |
| #985 | bug | low | Set Screenshot Directory is inconsistent with other Set ... keywords |
| #715 | enhancement | low | Support returning int from Get Matching Xpath Count |
| #794 | enhancement | low | Extend xpath detection to support xpath starting with (// |
| #920 | enhancement | low | Better names for Current Frame Contains, Focus and Simulate |
| #943 | enhancement | low | Wait For Condition should validate that condition contains return |
| #949 | enhancement | low | Enhancements to getting and validating element counts |
| #958 | enhancement | low | Wait Until Element Is Enabled should also check readonly status |
| #961 | enhancement | low | Make it an error to unregister a locator strategy that hasn't been registered |
Altogether 47 issues. View on the issue tracker.