@@ -322,6 +322,115 @@ class SeleniumLibrary(DynamicCore):
322322 https://robocon.io/, https://github.com/robotframework/'
323323 and 'https://github.com/.
324324
325+ = Browser and Driver options and service class =
326+
327+ This section talks about how to configure either the browser or
328+ the driver using the options and 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 launch Chromium-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+
407+ == Configuring the driver using the Service class ==
408+
409+ With the ``service`` argument, one can setup and configure the driver. For example
410+ one can set the driver location and/port or specify the command line arguments. There
411+ are several browser specific attributes related to logging as well. For the various
412+ Service Class attributes refer to
413+ [https://www.selenium.dev/documentation/webdriver/drivers/service/|the Selenium documentation]
414+ . Currently the ``service`` argument only accepts Selenium service in the string format.
415+
416+ === Service string format ===
417+
418+ The string format allows for defining Selenium service attributes
419+ and their values in the `Open Browser` keyword. The attributes names
420+ are case and space sensitive and must match to the Selenium attributes
421+ names. Attributes are defined in a similar way as in Python: attribute
422+ name, equal sign, and attribute value. Example, `port=1234`. Multiple
423+ attributes must be separated by a semicolon. Example:
424+ `executable_path='/path/to/driver';port=1234`. Don't have duplicate
425+ attributes, like `service_args=['--append-log', '--readable-timestamp'];
426+ service_args=['--log-level=DEBUG']` as the second will override the first.
427+ Instead combine them as in
428+ `service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']`
429+
430+ Arguments allow defining Python data types and arguments are
431+ evaluated by using Python. Strings must be quoted with single
432+ or double quotes, example "value" or 'value'
433+
325434 = Timeouts, waits, and delays =
326435
327436 This section discusses different ways how to wait for elements to
0 commit comments