Skip to content

Commit 56369d8

Browse files
pekkaklarckaaltat
pekkaklarck
authored and
aaltat
committed
README rewrite (#877)
1 parent a10a421 commit 56369d8

File tree

1 file changed

+147
-98
lines changed

1 file changed

+147
-98
lines changed

‎README.rst‎

Lines changed: 147 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,192 @@
11
SeleniumLibrary
22
===============
33

4-
.. image:: https://api.travis-ci.org/robotframework/SeleniumLibrary.png
5-
:target: http://travis-ci.org/robotframework/SeleniumLibrary
6-
7-
.. image:: https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version
8-
:target: https://pypi.python.org/pypi/robotframework-seleniumlibrary
9-
10-
.. image:: https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg
11-
:target: http://www.apache.org/licenses/LICENSE-2.0
4+
.. contents::
5+
:local:
126

137
Introduction
148
------------
159

16-
SeleniumLibrary is a web testing library for `Robot Framework`_ that utilizes
17-
the popular Selenium_ tool internally. See the `keyword documentation`_
18-
for available keywords and `wiki`_ for some more general information
19-
about the library.
10+
SeleniumLibrary_ is a web testing library for `Robot Framework`_
11+
that utilizes the Selenium_ tool internally. See `keyword documentation`_
12+
for available keywords and more information about the library in general.
13+
14+
SeleniumLibrary requires Selenium 2.53.6 or newer. It works with Python 2.7
15+
as well as with Python 3.3 or newer.
2016

2117
SeleniumLibrary is based on the `old SeleniumLibrary`_ that was forked to
22-
Selenium2Library and then later renamed back to SeleniumLibrary.
18+
Selenium2Library_ and then later renamed back to SeleniumLibrary.
19+
See the `History`_ section below for more information about different
20+
versions.
2321

2422
The new SeleniumLibrary is currently in pre-release phase. The final
2523
SeleniumLibrary 3.0 release is planned for early September.
2624

27-
The Selenium2Library 1.8.0 keyword `documentation is also available`_
25+
.. image:: https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version
26+
:target: https://pypi.python.org/pypi/robotframework-seleniumlibrary
27+
28+
.. image:: https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg
29+
:target: http://www.apache.org/licenses/LICENSE-2.0
30+
31+
.. image:: https://api.travis-ci.org/robotframework/SeleniumLibrary.png
32+
:target: http://travis-ci.org/robotframework/SeleniumLibrary
2833

2934
Installation
3035
------------
3136

3237
The recommended installation method is using pip_::
3338

34-
pip install --pre robotframework-seleniumlibrary
35-
36-
Notice that ``--pre`` is needed to get the current SeleniumLibrary,
37-
not the `old SeleniumLibrary`_, until the final SeleniumLibrary 3.0
38-
is released.
39-
40-
To install the old Selenium2Library, use this command instead::
41-
42-
pip install robotframework-selenium2library
39+
pip install --pre --upgrade robotframework-seleniumlibrary
4340

44-
See `INSTALL.rst`_ for more details about installation.
45-
46-
Usage
47-
-----
41+
Notice that the ``--pre`` option is needed to get the current SeleniumLibrary,
42+
not the `old SeleniumLibrary`_, until the final SeleniumLibrary 3.0 is
43+
released. The ``--upgrade`` option can be omitted when installing the
44+
library for the first time.
4845

49-
To write tests with Robot Framework and SeleniumLibrary,
50-
SeleniumLibrary must be imported into your Robot test suite.
51-
See `Robot Framework User Guide`_ for more information.
46+
Those migrating from Selenium2Library_ can install SeleniumLibrary so that
47+
it is exposed also as Selenium2Library::
5248

53-
A demo project illustrating how to use this library can be found from:
54-
https://bitbucket.org/robotframework/webdemo
49+
pip install --pre --upgrade robotframework-selenium2library
5550

56-
Differences between SeleniumLibrary versions
57-
============================================
51+
The above command installs the normal SeleniumLibrary as well as a new
52+
Selenium2Library version that is just a thin wrapper to SeleniumLibrary.
53+
That allows importing Selenium2Library in tests while migrating to
54+
SeleniumLibrary.
5855

59-
Selenium versions
60-
-----------------
56+
To install the last legacy Selenium2Library_ version, use this command instead::
6157

62-
There are three main version of Selenium: `Selenium Remote Control`_ (RC or Selenium
63-
1), `Selenium 2`_ and `Selenium 3`_.
58+
pip install robotframework-selenium2library==1.8.0
6459

65-
The Selenium RC works only with major browsers that has JavaScript enabled. It
66-
also requires a selenium server which automatically launches and kills browsers.
67-
The Selenium RC is not anymore maintained by the Selenium.
68-
69-
The Selenium 2 supports Selenium RC and Selenium WebDirver. Selenium WebDriver
70-
does not need separate server to launch and kill servers and it has simpler
71-
and more concise API then Selenium RC.
72-
73-
The Selenium 3 supports only Selenium WebDirver and has started to adopt
74-
the `W3C WebDriver`_ specification. If excluding the dropped Selenium RC
75-
support, Selenium 3 is a drop in replacement for Selenium 2.
76-
77-
Selenium support in Robot Framework
78-
-----------------------------------
79-
80-
The SeleniumLibrary version up to 2.9.2 supports only the Selenium RC.
81-
82-
The Selenium2Library versions up to 1.8.0 and from SeleniumLibrary 3.0.0
83-
version onwards supports Selenium 2 and 3
84-
85-
Python support
86-
--------------
87-
88-
The SeleniumLibrary version up to 2.9.2 and the Selenium2Library
89-
versions up to 1.8.0 supports only Python 2
90-
91-
Starting from SeleniumLibrary 3.0.0 version onwards Python 2 and Python 3.3+ are
92-
supported.
93-
94-
History
95-
-------
96-
97-
The SeleniumLibrary up to 2.9.2 version was actively developed by using the
98-
Selenium RC. When the Selenium 2 reached mature enough state, the Selenium2Library
99-
was forked from SeleniumLibary and modified to use the Selenium WebDriver. The
100-
SeleniumLibrary, with Selenium RC support, active development ended
101-
when Selenium RC was deprecated.
60+
See `INSTALL.rst`_ for more details about installation.
10261

103-
When Selenium 3 was released it was adopted by the Selenium2Library
104-
because Selenium 3 is a drop in replacement for Selenium 2. Also the
105-
Selenium2Library relies only on the WebDriver technology and it did not
106-
need any changes to support Selenium 3.
62+
Usage
63+
-----
10764

108-
In release 3.0.0, it was decided to rename the Selenium2Library back to
109-
SeleniumLibrary. This was done because the name more resembles what the library
110-
supports and enables.
65+
To use SeleniumLibrary in Robot Framework tests, the library needs to
66+
first be imported using the ``Library`` setting as any other library.
67+
The library accepts some import time arguments, which are documented
68+
in the `keyword documentation`_ along with all the keywords provided
69+
by the library.
70+
71+
When using Robot Framework, it is generally recommended to write as
72+
easy-to-understand tests as possible. The keywords provided by
73+
SeleniumLibrary are pretty low level, though, and often require
74+
implementation specific arguments like element locators to be passed
75+
as arguments. It is thus typically a good idea to write tests using
76+
Robot Framework's higher level keywords that utilize SeleniumLibrary
77+
keywords internally. This is illustrated by the following example
78+
where SeleniumLibrary keywords like ``Input Text`` are primarily
79+
used by higher level keywords like ``Input Username``.
80+
81+
.. code:: robotframework
82+
83+
*** Settings ***
84+
Documentation Simple example using SeleniumLibrary.
85+
Library SeleniumLibrary
86+
87+
*** Variables ***
88+
${LOGIN URL} http://localhost:7272
89+
${BROWSER} Chrome
90+
91+
*** Test Cases ***
92+
Valid Login
93+
Open Browser To Login Page
94+
Input Username demo
95+
Input Password mode
96+
Submit Credentials
97+
Welcome Page Should Be Open
98+
[Teardown] Close Browser
99+
100+
*** Keywords ***
101+
Open Browser To Login Page
102+
Open Browser ${LOGIN URL} ${BROWSER}
103+
Title Should Be Login Page
104+
105+
Input Username
106+
[Arguments] ${username}
107+
Input Text username_field ${username}
108+
109+
Input Password
110+
[Arguments] ${password}
111+
Input Text password_field ${password}
112+
113+
Submit Credentials
114+
Click Button login_button
115+
116+
Welcome Page Should Be Open
117+
Title Should Be Welcome Page
118+
119+
120+
The above example is a slightly modified version of an example in a
121+
`demo project`_ that illustrates using Robot Framework and SeleniumLibrary.
122+
See the demo for more examples that you can also execute on your own
123+
machine. For more information about Robot Framework test data syntax in
124+
general see `Robot Framework User Guide`_.
111125

112126
Support
113127
-------
114128

115-
Best places to ask for support:
129+
If the provided documentation is not enough, there are various support forums
130+
available:
116131

117132
- `robotframework-users`_ mailing list
118-
- ``#seleniumlibrary`` channel on `Robot Framework Slack`_
133+
- ``#seleniumlibrary`` and ``#seleniumlibrary-dev`` channels in
134+
Robot Framework `Slack community`_
135+
- SeleniumLibrary `issue tracker`_ for bug reports and concrete enhancement
136+
requests
137+
- `Other support forums`_ including paid support
119138

120-
When asking for help or reporting problems, please include the following
121-
information:
139+
History
140+
-------
122141

123-
- Full description of what you are trying to do and expected outcome
124-
- Version number of SeleniumLibrary, Selenium, and Robot Framework
125-
- Version number of the browser and the browser driver
126-
- Traceback or other debug output containing error information
142+
SeleniumLibrary originally used the Selenium Remote Controller (RC) API.
143+
When Selenium 2 was introduced with the new but backwards incompatible
144+
WebDriver API, SeleniumLibrary kept using Selenium RC and separate
145+
Selenium2Library using WebDriver was forked. These projects contained
146+
mostly the same keywords and in most cases Selenium2Library was a drop-in
147+
replacement for SeleniumLibrary.
148+
149+
Over the years development of the old SeleniumLibrary stopped and also
150+
the Selenium RC API it used was deprecated. Selenium2Library was developed
151+
further and replaced the old library as the de facto web testing library
152+
for Robot Framework.
153+
154+
When Selenium 3 was released in 2016, it was otherwise backwards compatible
155+
with Selenium 2, but the deprecated Selenium RC API was removed. This had two
156+
important effects:
157+
158+
- The old SeleniumLibrary could not anymore be used with new Selenium versions.
159+
This project was pretty much dead.
160+
- Selenium2Library was badly named as it supported Selenium 3 just fine.
161+
This project needed a new name.
162+
163+
At the same time when Selenium 3 was released, Selenium2Library was going
164+
through larger architecture changes in order to ease future maintenance and
165+
to make adding Python 3 support easier. With all these big internal and
166+
external changes, it made sense to rename Selenium2Library back to
167+
SeleniumLibrary. This decision basically meant following changes:
168+
169+
- Create separate repository for the `old SeleniumLibrary`_ to preserve
170+
its history since Selenium2Library was forked.
171+
- Rename Selenium2Library project and the library itself to SeleniumLibrary.
172+
- Add new Selenium2Library_ project to ease transitioning from Selenium2Library
173+
to SeleniumLibrary.
174+
175+
Going forward, all new development will happen in the new SeleniumLibrary
176+
project.
127177

128178
.. _Robot Framework: http://robotframework.org
129179
.. _Selenium: http://seleniumhq.org
130-
.. _Old SeleniumLibrary: https://github.com/robotframework/OldSeleniumLibrary/
180+
.. _SeleniumLibrary: https://github.com/robotframework/SeleniumLibrary
181+
.. _Selenium2Library: https://github.com/robotframework/Selenium2Library
182+
.. _Old SeleniumLibrary: https://github.com/robotframework/OldSeleniumLibrary
131183
.. _pip: http://pip-installer.org
132-
.. _Wiki: https://github.com/robotframework/SeleniumLibrary/wiki
133184
.. _Keyword Documentation: http://robotframework.org/SeleniumLibrary/SeleniumLibrary.html
134185
.. _INSTALL.rst: https://github.com/robotframework/SeleniumLibrary/blob/master/INSTALL.rst
135186
.. _BUILD.rst: https://github.com/robotframework/SeleniumLibrary/blob/master/BUILD.rst
187+
.. _demo project: https://bitbucket.org/robotframework/webdemo
136188
.. _Robot Framework User Guide: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html
137-
.. _Selenium Remote Control: http://www.seleniumhq.org/projects/remote-control/
138-
.. _Selenium 2: http://www.seleniumhq.org/projects/webdriver/
139-
.. _Selenium 3: http://www.seleniumhq.org/projects/webdriver/
140-
.. _W3C WebDriver: https://www.w3.org/TR/webdriver/
141189
.. _robotframework-users: http://groups.google.com/group/robotframework-users
142-
.. _Robot Framework Slack: https://robotframework-slack-invite.herokuapp.com/
143-
.. _documentation is also available: http://robotframework.org/SeleniumLibrary/Selenium2Library.html
190+
.. _Slack community: https://robotframework-slack-invite.herokuapp.com
191+
.. _issue tracker: https://github.com/robotframework/SeleniumLibrary/issues
192+
.. _Other support forums: http://robotframework.org/#support

0 commit comments

Comments
 (0)