forked from robotframework/SeleniumLibrary
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
279 lines (271 loc) · 20.5 KB
/
index.html
File metadata and controls
279 lines (271 loc) · 20.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8"/>
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>SeleniumLibrary</title>
<link rel="stylesheet" href="style.css" type="text/css" />
<link rel="stylesheet" href="extra.css" type="text/css" />
</head>
<body>
<div class="document" id="seleniumlibrary">
<h1 class="title">SeleniumLibrary</h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id6">Introduction</a></p></li>
<li><p><a class="reference internal" href="#keyword-documentation" id="id7">Keyword documentation</a></p></li>
<li><p><a class="reference internal" href="#installation" id="id8">Installation</a></p></li>
<li><p><a class="reference internal" href="#browser-drivers" id="id9">Browser drivers</a></p></li>
<li><p><a class="reference internal" href="#usage" id="id10">Usage</a></p></li>
<li><p><a class="reference internal" href="#extending-seleniumlibrary" id="id11">Extending SeleniumLibrary</a></p></li>
<li><p><a class="reference internal" href="#support" id="id12">Support</a></p></li>
<li><p><a class="reference internal" href="#versions" id="id13">Versions</a></p></li>
<li><p><a class="reference internal" href="#history" id="id14">History</a></p></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id6">Introduction</a></h1>
<p><a class="reference external" href="https://github.com/robotframework/SeleniumLibrary">SeleniumLibrary</a> is a web testing library for <a class="reference external" href="https://robotframework.org">Robot Framework</a> that
utilizes the <a class="reference external" href="https://seleniumhq.org">Selenium</a> tool internally. The project is hosted on <a class="reference external" href="https://github.com/robotframework/SeleniumLibrary">GitHub</a>
and downloads can be found from <a class="reference external" href="https://pypi.python.org/pypi/robotframework-seleniumlibrary">PyPI</a>.</p>
<p>SeleniumLibrary works with Selenium 3. It supports Python 2.7 as well as
Python 3.4 or newer. In addition to the normal <a class="reference external" href="https://python.org">Python</a> interpreter, it
works also with <a class="reference external" href="https://pypy.org">PyPy</a> and <a class="reference external" href="https://jython.org/">Jython</a>. Unfortunately <a class="reference external" href="https://seleniumhq.org">Selenium</a> is not
currently supported by <a class="reference external" href="https://ironpython.net/">IronPython</a> and thus this library does not work with
IronPython either.</p>
<p>SeleniumLibrary is based on the <a class="reference external" href="https://github.com/robotframework/OldSeleniumLibrary">old SeleniumLibrary</a> that was forked to
<a class="reference external" href="https://github.com/robotframework/Selenium2Library">Selenium2Library</a> and then later renamed back to SeleniumLibrary.
See the <a class="reference internal" href="#versions">Versions</a> and <a class="reference internal" href="#history">History</a> sections below for more information about
different versions and the overall project history.</p>
<a class="reference external image-reference" href="https://pypi.python.org/pypi/robotframework-seleniumlibrary"><img alt="https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version" src="https://img.shields.io/pypi/v/robotframework-seleniumlibrary.svg?label=version" /></a>
<a class="reference external image-reference" href="https://www.apache.org/licenses/LICENSE-2.0"><img alt="https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg" src="https://img.shields.io/pypi/l/robotframework-seleniumlibrary.svg" /></a>
<a class="reference external image-reference" href="https://travis-ci.org/robotframework/SeleniumLibrary"><img alt="https://api.travis-ci.org/robotframework/SeleniumLibrary.png" src="https://api.travis-ci.org/robotframework/SeleniumLibrary.png" /></a>
</div>
<div class="section" id="keyword-documentation">
<h1><a class="toc-backref" href="#id7">Keyword documentation</a></h1>
<p>See <a class="reference external" href="https://robotframework.org/SeleniumLibrary/SeleniumLibrary.html">keyword documentation</a> for available keywords and more information
about the library in general.</p>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#id8">Installation</a></h1>
<p>The recommended installation method is using <a class="reference external" href="http://pip-installer.org">pip</a>:</p>
<pre class="literal-block">pip install --upgrade robotframework-seleniumlibrary</pre>
<p>Running this command installs also the latest Selenium and Robot Framework
versions, but you still need to install <a class="reference internal" href="#browser-drivers">browser drivers</a> separately.
The <span class="docutils literal"><span class="pre">--upgrade</span></span> option can be omitted when installing the library for the
first time.</p>
<p>Those migrating from <a class="reference external" href="https://github.com/robotframework/Selenium2Library">Selenium2Library</a> can install SeleniumLibrary so that
it is exposed also as Selenium2Library:</p>
<pre class="literal-block">pip install --upgrade robotframework-selenium2library</pre>
<p>The above command installs the normal SeleniumLibrary as well as a new
Selenium2Library version that is just a thin wrapper to SeleniumLibrary.
That allows importing Selenium2Library in tests while migrating to
SeleniumLibrary.</p>
<p>To install the last legacy <a class="reference external" href="https://github.com/robotframework/Selenium2Library">Selenium2Library</a> version, use this command instead:</p>
<pre class="literal-block">pip install robotframework-selenium2library==1.8.0</pre>
<p>With resent versions of <span class="docutils literal">pip</span> it is possible to install directly from the
<a class="reference external" href="https://github.com/robotframework/SeleniumLibrary">GitHub</a> repository. To install latest source from the master branch, use
this command:</p>
<pre class="literal-block">pip install git+https://github.com/robotframework/SeleniumLibrary.git</pre>
<p>Please note that installation will take some time, because <span class="docutils literal">pip</span> will
clone the <a class="reference external" href="https://github.com/robotframework/SeleniumLibrary">SeleniumLibrary</a> project to a temporary directory and then
perform the installation.</p>
<p>See <a class="reference external" href="https://github.com/robotframework/robotframework/blob/master/INSTALL.rst">Robot Framework installation instructions</a> for detailed information
about installing Python and Robot Framework itself. For more details about
using <span class="docutils literal">pip</span> see <a class="reference external" href="http://pip-installer.org">its own documentation</a>.</p>
</div>
<div class="section" id="browser-drivers">
<h1><a class="toc-backref" href="#id9">Browser drivers</a></h1>
<p>After installing the library, you still need to install browser and
operating system specific browser drivers for all those browsers you
want to use in tests. These are the exact same drivers you need to use with
Selenium also when not using SeleniumLibrary. More information about
drivers can be found from <a class="reference external" href="https://seleniumhq.github.io/selenium/docs/api/py/index.html#drivers">Selenium documentation</a>.</p>
<p>The general approach to install a browser driver is downloading a right
driver, such as <span class="docutils literal">chromedriver</span> for Chrome, and placing it into
a directory that is in <a class="reference external" href="https://en.wikipedia.org/wiki/PATH_(variable)">PATH</a>. Drivers for different browsers
can be found via Selenium documentation or by using your favorite
search engine with a search term like <span class="docutils literal">selenium chrome browser driver</span>.
New browser driver versions are released to support features in
new browsers, fix bug, or otherwise, and you need to keep an eye on them
to know when to update drivers you use.</p>
<p>Alternatively, you can use a tool called <a class="reference external" href="https://github.com/omenia/webdrivermanager">WebdriverManager</a> which can
find the latest version or when required, any version of appropriate
webdrivers for you and then download and link/copy it into right
location. Tool can run on all major operating systems and supports
downloading of Chrome, Firefox, Opera & Edge webdrivers.</p>
<p>Here's an example:</p>
<pre class="code bash literal-block"><code>pip install webdrivermanager
webdrivermanager firefox chrome --linkpath /usr/local/bin</code></pre>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id10">Usage</a></h1>
<p>To use SeleniumLibrary in Robot Framework tests, the library needs to
first be imported using the <span class="docutils literal">Library</span> setting as any other library.
The library accepts some import time arguments, which are documented
in the <a class="reference external" href="https://robotframework.org/SeleniumLibrary/SeleniumLibrary.html">keyword documentation</a> along with all the keywords provided
by the library.</p>
<p>When using Robot Framework, it is generally recommended to write as
easy-to-understand tests as possible. The keywords provided by
SeleniumLibrary are pretty low level, though, and often require
implementation specific arguments like element locators to be passed
as arguments. It is thus typically a good idea to write tests using
Robot Framework's higher level keywords that utilize SeleniumLibrary
keywords internally. This is illustrated by the following example
where SeleniumLibrary keywords like <span class="docutils literal">Input Text</span> are primarily
used by higher level keywords like <span class="docutils literal">Input Username</span>.</p>
<pre class="code robotframework literal-block"><code><span class="generic heading">*** Settings ***</span><span class="punctuation">
</span><span class="keyword namespace">Documentation</span><span class="punctuation"> </span><span class="literal string">Simple example using SeleniumLibrary.</span><span class="punctuation">
</span><span class="keyword namespace">Library</span><span class="punctuation"> </span><span class="name namespace">SeleniumLibrary</span><span class="punctuation">
</span><span class="generic heading">*** Variables ***</span><span class="punctuation">
${</span><span class="name variable">LOGIN URL</span><span class="punctuation">} </span><span class="literal string">http://localhost:7272</span><span class="punctuation">
${</span><span class="name variable">BROWSER</span><span class="punctuation">} </span><span class="literal string">Chrome</span><span class="punctuation">
</span><span class="generic heading">*** Test Cases ***</span><span class="punctuation">
</span><span class="generic subheading">Valid Login</span><span class="punctuation">
</span><span class="name function">Open Browser To Login Page</span><span class="punctuation">
</span><span class="name function">Input Username</span><span class="punctuation"> </span><span class="literal string">demo</span><span class="punctuation">
</span><span class="name function">Input Password</span><span class="punctuation"> </span><span class="literal string">mode</span><span class="punctuation">
</span><span class="name function">Submit Credentials</span><span class="punctuation">
</span><span class="name function">Welcome Page Should Be Open</span><span class="punctuation">
[</span><span class="keyword namespace">Teardown</span><span class="punctuation">] </span><span class="name function">Close Browser</span><span class="punctuation">
</span><span class="generic heading">*** Keywords ***</span><span class="punctuation">
</span><span class="generic subheading">Open Browser To Login Page</span><span class="punctuation">
</span><span class="name function">Open Browser</span><span class="punctuation"> ${</span><span class="name variable">LOGIN URL</span><span class="punctuation">} ${</span><span class="name variable">BROWSER</span><span class="punctuation">}
</span><span class="name function">Title Should Be</span><span class="punctuation"> </span><span class="literal string">Login Page</span><span class="punctuation">
</span><span class="generic subheading">Input Username</span><span class="punctuation">
[</span><span class="keyword namespace">Arguments</span><span class="punctuation">] ${</span><span class="name variable">username</span><span class="punctuation">}
</span><span class="name function">Input Text</span><span class="punctuation"> </span><span class="literal string">username_field</span><span class="punctuation"> ${</span><span class="name variable">username</span><span class="punctuation">}
</span><span class="generic subheading">Input Password</span><span class="punctuation">
[</span><span class="keyword namespace">Arguments</span><span class="punctuation">] ${</span><span class="name variable">password</span><span class="punctuation">}
</span><span class="name function">Input Text</span><span class="punctuation"> </span><span class="literal string">password_field</span><span class="punctuation"> ${</span><span class="name variable">password</span><span class="punctuation">}
</span><span class="generic subheading">Submit Credentials</span><span class="punctuation">
</span><span class="name function">Click Button</span><span class="punctuation"> </span><span class="literal string">login_button</span><span class="punctuation">
</span><span class="generic subheading">Welcome Page Should Be Open</span><span class="punctuation">
</span><span class="name function">Title Should Be</span><span class="punctuation"> </span><span class="literal string">Welcome Page</span></code></pre>
<p>The above example is a slightly modified version of an example in a
<a class="reference external" href="https://github.com/robotframework/WebDemo">demo project</a> that illustrates using Robot Framework and SeleniumLibrary.
See the demo for more examples that you can also execute on your own
machine. For more information about Robot Framework test data syntax in
general see the <a class="reference external" href="https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html">Robot Framework User Guide</a>.</p>
</div>
<div class="section" id="extending-seleniumlibrary">
<h1><a class="toc-backref" href="#id11">Extending SeleniumLibrary</a></h1>
<p>Before creating your own library which extends the <span class="docutils literal">SeleniumLibrary</span>, please consider would
the extension be also useful also for general usage. If it could be useful also for general
usage, please create a new issue describing the enhancement request and even better if the
issue is backed up by a pull request.</p>
<p>If the enhancement is not generally useful, example solution is domain specific, then the
SeleniumLibrary 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 internal
functionality of the library. Also new libraries can be build on top of the
SeleniumLibrary. Please see <a class="reference external" href="https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst">extending documentation</a> for more details about the
available methods and for examples how the library can be extended.</p>
</div>
<div class="section" id="support">
<h1><a class="toc-backref" href="#id12">Support</a></h1>
<p>If the provided documentation is not enough, there are various support forums
available:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://groups.google.com/group/robotframework-users">robotframework-users</a> mailing list</p></li>
<li><p><span class="docutils literal">#seleniumlibrary</span> and <span class="docutils literal"><span class="pre">#seleniumlibrary-dev</span></span> channels in
Robot Framework <a class="reference external" href="https://robotframework-slack-invite.herokuapp.com">Slack community</a></p></li>
<li><p>SeleniumLibrary <a class="reference external" href="https://github.com/robotframework/SeleniumLibrary/issues">issue tracker</a> for bug reports and concrete enhancement
requests</p></li>
<li><p><a class="reference external" href="https://robotframework.org/#support">Other support forums</a> including paid support</p></li>
</ul>
</div>
<div class="section" id="versions">
<h1><a class="toc-backref" href="#id13">Versions</a></h1>
<p>SeleniumLibrary has over the years lived under SeleniumLibrary and
Selenium2Library names and different library versions have supported
different Selenium and Python versions. This is summarized in the table
below and the <a class="reference internal" href="#history">History</a> section afterwards explains the project history
a bit more.</p>
<table>
<colgroup>
<col style="width: 22%" />
<col style="width: 16%" />
<col style="width: 16%" />
<col style="width: 46%" />
</colgroup>
<thead>
<tr><th class="head"><p>Project</p></th>
<th class="head"><p>Selenium Version</p></th>
<th class="head"><p>Python Version</p></th>
<th class="head"><p>Comment</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>SeleniumLibrary 2.9.2 and earlier</p></td>
<td><p>Selenium 1 and 2</p></td>
<td><p>Python 2.5-2.7</p></td>
<td><p>The original SeleniumLibrary using Selenium RC API.</p></td>
</tr>
<tr><td><p>Selenium2Library 1.8.0 and earlier</p></td>
<td><p>Selenium 2 and 3</p></td>
<td><p>Python 2.6-2.7</p></td>
<td><p>Fork of SeleniumLibrary using Selenium WebDriver API.</p></td>
</tr>
<tr><td><p>SeleniumLibrary 3.0 and 3.1</p></td>
<td><p>Selenium 2 and 3</p></td>
<td><p>Python 2.7 and 3.3+</p></td>
<td><p>Selenium2Library renamed and with Python 3 support and new architecture.</p></td>
</tr>
<tr><td><p>SeleniumLibrary 3.2</p></td>
<td><p>Selenium 3</p></td>
<td><p>Python 2.7 and 3.4+</p></td>
<td><p>Drops Selenium 2 support.</p></td>
</tr>
<tr><td><p>SeleniumLibrary 4.0</p></td>
<td><p>Selenium 3</p></td>
<td><p>Python 2.7 and 3.4+</p></td>
<td><p>Plugin API and support for event friging webdriver.</p></td>
</tr>
<tr><td><p>Selenium2Library 3.0</p></td>
<td><p>Depends on SeleniumLibrary</p></td>
<td><p>Depends on SeleniumLibrary</p></td>
<td><p>Thin wrapper for SeleniumLibrary 3.0 to ease transition.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="history">
<h1><a class="toc-backref" href="#id14">History</a></h1>
<p>SeleniumLibrary originally used the Selenium Remote Controller (RC) API.
When Selenium 2 was introduced with the new but backwards incompatible
WebDriver API, SeleniumLibrary kept using Selenium RC and separate
Selenium2Library using WebDriver was forked. These projects contained
mostly the same keywords and in most cases Selenium2Library was a drop-in
replacement for SeleniumLibrary.</p>
<p>Over the years development of the old SeleniumLibrary stopped and also
the Selenium RC API it used was deprecated. Selenium2Library was developed
further and replaced the old library as the de facto web testing library
for Robot Framework.</p>
<p>When Selenium 3 was released in 2016, it was otherwise backwards compatible
with Selenium 2, but the deprecated Selenium RC API was removed. This had two
important effects:</p>
<ul class="simple">
<li><p>The old SeleniumLibrary could not anymore be used with new Selenium versions.
This project was pretty much dead.</p></li>
<li><p>Selenium2Library was badly named as it supported Selenium 3 just fine.
This project needed a new name.</p></li>
</ul>
<p>At the same time when Selenium 3 was released, Selenium2Library was going
through larger architecture changes in order to ease future maintenance and
to make adding Python 3 support easier. With all these big internal and
external changes, it made sense to rename Selenium2Library back to
SeleniumLibrary. This decision basically meant following changes:</p>
<ul class="simple">
<li><p>Create separate repository for the <a class="reference external" href="https://github.com/robotframework/OldSeleniumLibrary">old SeleniumLibrary</a> to preserve
its history since Selenium2Library was forked.</p></li>
<li><p>Rename Selenium2Library project and the library itself to <a class="reference external" href="https://github.com/robotframework/SeleniumLibrary">SeleniumLibrary</a>.</p></li>
<li><p>Add new <a class="reference external" href="https://github.com/robotframework/Selenium2Library">Selenium2Library</a> project to ease transitioning from Selenium2Library
to SeleniumLibrary.</p></li>
</ul>
<p>Going forward, all new development will happen in the new SeleniumLibrary
project.</p>
</div>
</div>
</body>
</html>