Skip to content

Commit 81f7d0c

Browse files
emanloveemanlove
committed
Initial reworking of the Open Browser keyword documentation
A major overhaul of the keyword documentation for `Open Browser`. - Added some deprecation warnings for ``service_log_path`` and ``executable_path`` options. Also noted that the already deprecated ``desired_capabilities`` will be removed in the next release. - Removed note about partial support for options as it is now full support. - Moved majority of options description up to the main library documentation. - Reshuffled examples and put them closery to the arguments they demonstarte. - Removed many of the "this feature was added in version x" messages as they are very old changes.
1 parent e34282e commit 81f7d0c

File tree

2 files changed

+117
-109
lines changed

2 files changed

+117
-109
lines changed

‎src/SeleniumLibrary/__init__.py‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,88 @@ class SeleniumLibrary(DynamicCore):
322322
https://robocon.io/, https://github.com/robotframework/'
323323
and 'https://github.com/.
324324
325+
= Browser and Driver options =
326+
327+
This section talks about how to configure either the browser or
328+
the driver using the options ans service arguments of the `Open
329+
Browser` keyword.
330+
331+
== Configuring the browser using the Selenium Options ==
332+
333+
As noted within the keyword documentation for `Open Browser`, its
334+
``options`` argument accepts Selenium options in two different
335+
formats: as a string and as Python object which is an instance of
336+
the Selenium options class.
337+
338+
=== Options string format ===
339+
340+
The string format allows defining Selenium options methods
341+
or attributes and their arguments in Robot Framework test data.
342+
The method and attributes names are case and space sensitive and
343+
must match to the Selenium options methods and attributes names.
344+
When defining a method, it must be defined in a similar way as in
345+
python: method name, opening parenthesis, zero to many arguments
346+
and closing parenthesis. If there is a need to define multiple
347+
arguments for a single method, arguments must be separated with
348+
comma, just like in Python. Example: `add_argument("--headless")`
349+
or `add_experimental_option("key", "value")`. Attributes are
350+
defined in a similar way as in Python: attribute name, equal sign,
351+
and attribute value. Example, `headless=True`. Multiple methods
352+
and attributes must be separated by a semicolon. Example:
353+
`add_argument("--headless");add_argument("--start-maximized")`.
354+
355+
Arguments allow defining Python data types and arguments are
356+
evaluated by using Python
357+
[https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].
358+
Strings must be quoted with single or double quotes, example "value"
359+
or 'value'. It is also possible to define other Python builtin
360+
data types, example `True` or `None`, by not using quotes
361+
around the arguments.
362+
363+
The string format is space friendly. Usually, spaces do not alter
364+
the defining methods or attributes. There are two exceptions.
365+
In some Robot Framework test data formats, two or more spaces are
366+
considered as cell separator and instead of defining a single
367+
argument, two or more arguments may be defined. Spaces in string
368+
arguments are not removed and are left as is. Example
369+
`add_argument ( "--headless" )` is same as
370+
`add_argument("--headless")`. But `add_argument(" --headless ")` is
371+
not same same as `add_argument ( "--headless" )`, because
372+
spaces inside of quotes are not removed. Please note that if
373+
options string contains backslash, example a Windows OS path,
374+
the backslash needs escaping both in Robot Framework data and
375+
in Python side. This means single backslash must be writen using
376+
four backslash characters. Example, Windows path:
377+
"C:\\path\\to\\profile" must be written as
378+
"C:\\\\\\\\path\\\\\\to\\\\\\\\profile". Another way to write
379+
backslash is use Python
380+
[https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]
381+
and example write: r"C:\\\\path\\\\to\\\\profile".
382+
383+
=== Selenium Options as Python class ===
384+
385+
As last format, ``options`` argument also supports receiving
386+
the Selenium options as Python class instance. In this case, the
387+
instance is used as-is and the SeleniumLibrary will not convert
388+
the instance to other formats.
389+
For example, if the following code return value is saved to
390+
`${options}` variable in the Robot Framework data:
391+
| options = webdriver.ChromeOptions()
392+
| options.add_argument('--disable-dev-shm-usage')
393+
| return options
394+
395+
Then the `${options}` variable can be used as an argument to
396+
``options``.
397+
398+
Example the ``options`` argument can be used to launch Chomium-based
399+
applications which utilize the
400+
[https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]
401+
. To lauch Chomium-based application, use ``options`` to define
402+
`binary_location` attribute and use `add_argument` method to define
403+
`remote-debugging-port` port for the application. Once the browser
404+
is opened, the test can interact with the embedded web-content of
405+
the system under test.
406+
325407
= Timeouts, waits, and delays =
326408
327409
This section discusses different ways how to wait for elements to

‎src/SeleniumLibrary/keywords/browsermanagement.py‎

Lines changed: 35 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -88,13 +88,18 @@ def open_browser(
8888
To be able to actually use one of these browsers, you need to have
8989
a matching Selenium browser driver available. See the
9090
[https://github.com/robotframework/SeleniumLibrary#browser-drivers|
91-
project documentation] for more details. Headless Firefox and
92-
Headless Chrome are new additions in SeleniumLibrary 3.1.0
93-
and require Selenium 3.8.0 or newer.
91+
project documentation] for more details.
9492
9593
After opening the browser, it is possible to use optional
9694
``url`` to navigate the browser to the desired address.
9795
96+
Examples:
97+
| `Open Browser` | http://example.com | Chrome | |
98+
| `Open Browser` | http://example.com | Firefox | alias=Firefox |
99+
| `Open Browser` | http://example.com | Edge | remote_url=http://127.0.0.1:4444/wd/hub |
100+
| `Open Browser` | about:blank | | |
101+
| `Open Browser` | browser=Chrome | | |
102+
98103
Optional ``alias`` is an alias given for this browser instance and
99104
it can be used for switching between browsers. When same ``alias``
100105
is given with two `Open Browser` keywords, the first keyword will
@@ -108,18 +113,26 @@ def open_browser(
108113
browsers are opened, and reset back to 1 when `Close All Browsers`
109114
is called. See `Switch Browser` for more information and examples.
110115
116+
Alias examples:
117+
| ${1_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Opens new browser because alias is new. |
118+
| ${2_index} = | `Open Browser` | http://example.com | Firefox | | # Opens new browser because alias is not defined. |
119+
| ${3_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Switches to the browser with Chrome alias. |
120+
| ${4_index} = | `Open Browser` | http://example.com | Chrome | alias=${1_index} | # Switches to the browser with Chrome alias. |
121+
| Should Be Equal | ${1_index} | ${3_index} | | | |
122+
| Should Be Equal | ${1_index} | ${4_index} | | | |
123+
| Should Be Equal | ${2_index} | ${2} | | | |
124+
111125
Optional ``remote_url`` is the URL for a
112126
[https://github.com/SeleniumHQ/selenium/wiki/Grid2|Selenium Grid].
113127
114-
Optional ``desired_capabilities`` is deprecated and will be ignored. Capabilities of each
115-
individual browser is now done through options or services. Please refer to those arguments
128+
Optional ``desired_capabilities`` is deprecated and will be removed
129+
in the next release. Capabilities of each individual browser is now
130+
done through options or services. Please refer to those arguments
116131
for configuring specific browsers.
117132
118133
Optional ``ff_profile_dir`` is the path to the Firefox profile
119134
directory if you wish to overwrite the default profile Selenium
120-
uses. Notice that prior to SeleniumLibrary 3.0, the library
121-
contained its own profile that was used by default. The
122-
``ff_profile_dir`` can also be an instance of the
135+
uses. The ``ff_profile_dir`` can also be an instance of the
123136
[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_firefox/selenium.webdriver.firefox.firefox_profile.html|selenium.webdriver.FirefoxProfile]
124137
. As a third option, it is possible to use `FirefoxProfile` methods
125138
and attributes to define the profile using methods and attributes
@@ -128,86 +141,28 @@ def open_browser(
128141
profile settings. See ``options`` argument documentation in below
129142
how to handle backslash escaping.
130143
144+
Example for FirefoxProfile
145+
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=/path/to/profile | # Using profile from disk. |
146+
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=${FirefoxProfile_instance} | # Using instance of FirefoxProfile. |
147+
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=set_preference("key", "value");set_preference("other", "setting") | # Defining profile using FirefoxProfile mehtods. |
148+
131149
Optional ``options`` argument allows defining browser specific
132150
Selenium options. Example for Chrome, the ``options`` argument
133151
allows defining the following
134152
[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_chrome/selenium.webdriver.chrome.options.html#selenium.webdriver.chrome.options.Options|methods and attributes]
135153
and for Firefox these
136154
[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_firefox/selenium.webdriver.firefox.options.html?highlight=firefox#selenium.webdriver.firefox.options.Options|methods and attributes]
137-
are available. Please note that not all browsers, supported by the
138-
SeleniumLibrary, have Selenium options available. Therefore please
139-
consult the Selenium documentation which browsers do support
140-
the Selenium options. Selenium options are also supported, when ``remote_url``
155+
are available. Selenium options are also supported, when ``remote_url``
141156
argument is used.
142157
143158
The SeleniumLibrary ``options`` argument accepts Selenium
144159
options in two different formats: as a string and as Python object
145160
which is an instance of the Selenium options class.
146161
147-
The string format allows defining Selenium options methods
148-
or attributes and their arguments in Robot Framework test data.
149-
The method and attributes names are case and space sensitive and
150-
must match to the Selenium options methods and attributes names.
151-
When defining a method, it must be defined in a similar way as in
152-
python: method name, opening parenthesis, zero to many arguments
153-
and closing parenthesis. If there is a need to define multiple
154-
arguments for a single method, arguments must be separated with
155-
comma, just like in Python. Example: `add_argument("--headless")`
156-
or `add_experimental_option("key", "value")`. Attributes are
157-
defined in a similar way as in Python: attribute name, equal sign,
158-
and attribute value. Example, `headless=True`. Multiple methods
159-
and attributes must be separated by a semicolon. Example:
160-
`add_argument("--headless");add_argument("--start-maximized")`.
161-
162-
Arguments allow defining Python data types and arguments are
163-
evaluated by using Python
164-
[https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].
165-
Strings must be quoted with single or double quotes, example "value"
166-
or 'value'. It is also possible to define other Python builtin
167-
data types, example `True` or `None`, by not using quotes
168-
around the arguments.
169-
170-
The string format is space friendly. Usually, spaces do not alter
171-
the defining methods or attributes. There are two exceptions.
172-
In some Robot Framework test data formats, two or more spaces are
173-
considered as cell separator and instead of defining a single
174-
argument, two or more arguments may be defined. Spaces in string
175-
arguments are not removed and are left as is. Example
176-
`add_argument ( "--headless" )` is same as
177-
`add_argument("--headless")`. But `add_argument(" --headless ")` is
178-
not same same as `add_argument ( "--headless" )`, because
179-
spaces inside of quotes are not removed. Please note that if
180-
options string contains backslash, example a Windows OS path,
181-
the backslash needs escaping both in Robot Framework data and
182-
in Python side. This means single backslash must be writen using
183-
four backslash characters. Example, Windows path:
184-
"C:\\path\\to\\profile" must be written as
185-
"C:\\\\\\\\path\\\\\\to\\\\\\\\profile". Another way to write
186-
backslash is use Python
187-
[https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]
188-
and example write: r"C:\\\\path\\\\to\\\\profile".
189-
190-
As last format, ``options`` argument also supports receiving
191-
the Selenium options as Python class instance. In this case, the
192-
instance is used as-is and the SeleniumLibrary will not convert
193-
the instance to other formats.
194-
For example, if the following code return value is saved to
195-
`${options}` variable in the Robot Framework data:
196-
| options = webdriver.ChromeOptions()
197-
| options.add_argument('--disable-dev-shm-usage')
198-
| return options
199-
200-
Then the `${options}` variable can be used as an argument to
201-
``options``.
202-
203-
Example the ``options`` argument can be used to launch Chomium-based
204-
applications which utilize the
205-
[https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]
206-
. To lauch Chomium-based application, use ``options`` to define
207-
`binary_location` attribute and use `add_argument` method to define
208-
`remote-debugging-port` port for the application. Once the browser
209-
is opened, the test can interact with the embedded web-content of
210-
the system under test.
162+
The string format ...
163+
164+
``options`` argument also supports receiving the Selenium
165+
options as Python class instance. ...
211166
212167
Optional ``service_log_path`` argument defines the name of the
213168
file where to write the browser driver logs. If the
@@ -223,22 +178,6 @@ def open_browser(
223178
it is assumed the executable is in the
224179
[https://en.wikipedia.org/wiki/PATH_(variable)|$PATH].
225180
226-
Examples:
227-
| `Open Browser` | http://example.com | Chrome | |
228-
| `Open Browser` | http://example.com | Firefox | alias=Firefox |
229-
| `Open Browser` | http://example.com | Edge | remote_url=http://127.0.0.1:4444/wd/hub |
230-
| `Open Browser` | about:blank | | |
231-
| `Open Browser` | browser=Chrome | | |
232-
233-
Alias examples:
234-
| ${1_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Opens new browser because alias is new. |
235-
| ${2_index} = | `Open Browser` | http://example.com | Firefox | | # Opens new browser because alias is not defined. |
236-
| ${3_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Switches to the browser with Chrome alias. |
237-
| ${4_index} = | `Open Browser` | http://example.com | Chrome | alias=${1_index} | # Switches to the browser with Chrome alias. |
238-
| Should Be Equal | ${1_index} | ${3_index} | | | |
239-
| Should Be Equal | ${1_index} | ${4_index} | | | |
240-
| Should Be Equal | ${2_index} | ${2} | | | |
241-
242181
Example when using
243182
[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_chrome/selenium.webdriver.chrome.options.html#selenium.webdriver.chrome.options.Options|Chrome options]
244183
method:
@@ -248,28 +187,15 @@ def open_browser(
248187
| `Open Browser` | None | Chrome | options=binary_location="/path/to/binary";add_argument("remote-debugging-port=port") | # Start Chomium-based application. |
249188
| `Open Browser` | None | Chrome | options=binary_location=r"C:\\\\path\\\\to\\\\binary" | # Windows OS path escaping. |
250189
251-
Example for FirefoxProfile
252-
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=/path/to/profile | # Using profile from disk. |
253-
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=${FirefoxProfile_instance} | # Using instance of FirefoxProfile. |
254-
| `Open Browser` | http://example.com | Firefox | ff_profile_dir=set_preference("key", "value");set_preference("other", "setting") | # Defining profile using FirefoxProfile mehtods. |
190+
Optional ``service`` argument allows for managing the local drivers
191+
as well as setting some browser specific settings like logging. Service
192+
classes are not supported when ``remote_url`` argument is used.
255193
256194
If the provided configuration options are not enough, it is possible
257195
to use `Create Webdriver` to customize browser initialization even
258196
more.
259197
260-
Applying ``desired_capabilities`` argument also for local browser is
261-
new in SeleniumLibrary 3.1.
262-
263-
Using ``alias`` to decide, is the new browser opened is new
264-
in SeleniumLibrary 4.0. The ``options`` and ``service_log_path``
265-
are new in SeleniumLibrary 4.0. Support for ``ff_profile_dir``
266-
accepting an instance of the `selenium.webdriver.FirefoxProfile`
267-
and support defining FirefoxProfile with methods and
268-
attributes are new in SeleniumLibrary 4.0.
269-
270-
Making ``url`` optional is new in SeleniumLibrary 4.1.
271-
272-
The ``executable_path`` argument is new in SeleniumLibrary 4.2.
198+
The ``service`` argument is new in SeleniumLibrary 6.4.
273199
"""
274200
index = self.drivers.get_index(alias)
275201
if index:

0 commit comments

Comments
 (0)