diff --git a/pyproject.toml b/pyproject.toml index 2e56497..3b6c9fe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ authors = [ license = {file = "LICENSE"} description = "Robot Framework SeleniumLibrary localization project for all translations." readme = "README.md" -requires-python = ">=3.0" +requires-python = ">=3.8" classifiers = [ "Development Status :: 5 - Production/Stable", "Framework :: Robot Framework :: Library", @@ -26,7 +26,7 @@ classifiers = [ ] keywords = ["Robot Framework", "SeleniumLibrary"] -dependencies = ["robotframework-seleniumlibrary >= 6.7.0"] +dependencies = ["robotframework-seleniumlibrary >= 6.7.1"] [project.urls] Homepage = "https://github.com/MarketSquare/robotframework-seleniumlibrary-translation" diff --git a/robotframework_seleniumlibrary_translation/translation_fi.json b/robotframework_seleniumlibrary_translation/translation_fi.json index d458ec6..70c48e0 100644 --- a/robotframework_seleniumlibrary_translation/translation_fi.json +++ b/robotframework_seleniumlibrary_translation/translation_fi.json @@ -911,12 +911,12 @@ }, "__init__": { "name": "__init__", - "doc": "SeleniumLibrary is a web testing library for Robot Framework.\n\nThis document explains how to use keywords provided by SeleniumLibrary.\nFor information about installation, support, and more, please visit the\n[https://github.com/robotframework/SeleniumLibrary|project pages].\nFor more information about Robot Framework, see http://robotframework.org.\n\nSeleniumLibrary uses the Selenium WebDriver modules internally to\ncontrol a web browser. See http://seleniumhq.org for more information\nabout Selenium in general and SeleniumLibrary README.rst\n[https://github.com/robotframework/SeleniumLibrary#browser-drivers|Browser drivers chapter]\nfor more details about WebDriver binary installation.\n\n%TOC%\n\n= Locating elements =\n\nAll keywords in SeleniumLibrary that need to interact with an element\non a web page take an argument typically named ``locator`` that specifies\nhow to find the element. Most often the locator is given as a string\nusing the locator syntax described below, but `using WebElements` is\npossible too.\n\n== Locator syntax ==\n\nSeleniumLibrary supports finding elements based on different strategies\nsuch as the element id, XPath expressions, or CSS selectors. The strategy\ncan either be explicitly specified with a prefix or the strategy can be\nimplicit.\n\n=== Default locator strategy ===\n\nBy default, locators are considered to use the keyword specific default\nlocator strategy. All keywords support finding elements based on ``id``\nand ``name`` attributes, but some keywords support additional attributes\nor other values that make sense in their context. For example, `Click\nLink` supports the ``href`` attribute and the link text and addition\nto the normal ``id`` and ``name``.\n\nExamples:\n\n| `Click Element` | example | # Match based on ``id`` or ``name``. |\n| `Click Link` | example | # Match also based on link text and ``href``. |\n| `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. |\n\nIf a locator accidentally starts with a prefix recognized as `explicit\nlocator strategy` or `implicit XPath strategy`, it is possible to use\nthe explicit ``default`` prefix to enable the default strategy.\n\nExamples:\n\n| `Click Element` | name:foo | # Find element with name ``foo``. |\n| `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. |\n| `Click Element` | //foo | # Find element using XPath ``//foo``. |\n| `Click Element` | default: //foo | # Use default strategy with value ``//foo``. |\n\n=== Explicit locator strategy ===\n\nThe explicit locator strategy is specified with a prefix using either\nsyntax ``strategy:value`` or ``strategy=value``. The former syntax\nis preferred because the latter is identical to Robot Framework's\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax|\nnamed argument syntax] and that can cause problems. Spaces around\nthe separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo``\nare all equivalent.\n\nLocator strategies that are supported by default are listed in the table\nbelow. In addition to them, it is possible to register `custom locators`.\n\n| = Strategy = | = Match based on = | = Example = |\n| id | Element ``id``. | ``id:example`` |\n| name | ``name`` attribute. | ``name:example`` |\n| identifier | Either ``id`` or ``name``. | ``identifier:example`` |\n| class | Element ``class``. | ``class:example`` |\n| tag | Tag name. | ``tag:div`` |\n| xpath | XPath expression. | ``xpath://div[@id=\"example\"]`` |\n| css | CSS selector. | ``css:div#example`` |\n| dom | DOM expression. | ``dom:document.images[5]`` |\n| link | Exact text a link has. | ``link:The example`` |\n| partial link | Partial link text. | ``partial link:he ex`` |\n| sizzle | Sizzle selector deprecated. | ``sizzle:div.example`` |\n| data | Element ``data-*`` attribute | ``data:id:my_id`` |\n| jquery | jQuery expression. | ``jquery:div.example`` |\n| default | Keyword specific default behavior. | ``default:example`` |\n\nSee the `Default locator strategy` section below for more information\nabout how the default strategy works. Using the explicit ``default``\nprefix is only necessary if the locator value itself accidentally\nmatches some of the explicit strategies.\n\nDifferent locator strategies have different pros and cons. Using ids,\neither explicitly like ``id:foo`` or by using the `default locator\nstrategy` simply like ``foo``, is recommended when possible, because\nthe syntax is simple and locating elements by id is fast for browsers.\nIf an element does not have an id or the id is not stable, other\nsolutions need to be used. If an element has a unique tag name or class,\nusing ``tag``, ``class`` or ``css`` strategy like ``tag:h1``,\n``class:example`` or ``css:h1.example`` is often an easy solution. In\nmore complex cases using XPath expressions is typically the best\napproach. They are very powerful but a downside is that they can also\nget complex.\n\nExamples:\n\n| `Click Element` | id:foo | # Element with id 'foo'. |\n| `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. |\n| `Click Element` | xpath: //div[@id=\"foo\"]//h1 | # Same as the above using XPath, not CSS. |\n| `Click Element` | xpath: //*[contains(text(), \"example\")] | # Element containing text 'example'. |\n\n*NOTE:*\n\n- The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0\n and newer.\n- Using the ``sizzle`` strategy or its alias ``jquery`` requires that\n the system under test contains the jQuery library.\n- Prior to SeleniumLibrary 3.0, table related keywords only supported\n ``xpath``, ``css`` and ``sizzle/jquery`` strategies.\n- ``data`` strategy is conveniance locator that will construct xpath from the parameters.\n If you have element like `
`, you locate the element via\n ``data:automation:automation-id-2``. This feature was added in SeleniumLibrary 5.2.0\n\n=== Implicit XPath strategy ===\n\nIf the locator starts with ``//`` or multiple opening parenthesis in front\nof the ``//``, the locator is considered to be an XPath expression. In other\nwords, using ``//div`` is equivalent to using explicit ``xpath://div`` and\n``((//div))`` is equivalent to using explicit ``xpath:((//div))``\n\nExamples:\n\n| `Click Element` | //div[@id=\"foo\"]//h1 |\n| `Click Element` | (//div)[2] |\n\nThe support for the ``(//`` prefix is new in SeleniumLibrary 3.0.\nSupporting multiple opening parenthesis is new in SeleniumLibrary 5.0.\n\n=== Chaining locators ===\n\nIt is possible chain multiple locators together as single locator. Each chained locator must start with locator\nstrategy. Chained locators must be separated with single space, two greater than characters and followed with\nspace. It is also possible mix different locator strategies, example css or xpath. Also a list can also be\nused to specify multiple locators. This is useful, is some part of locator would match as the locator separator\nbut it should not. Or if there is need to existing WebElement as locator.\n\nAlthough all locators support chaining, some locator strategies do not abey the chaining. This is because\nsome locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context\nand not for the element found be the previous locator. Chaining is supported by locator strategies which\nare based on Selenium API, like `xpath` or `css`, but example chaining is not supported by `sizzle` or `jquery\n\nExamples:\n| `Click Element` | css:.bar >> xpath://a | # To find a link which is present after an element with class \"bar\" |\n\nList examples:\n| ${locator_list} = | `Create List` | css:div#div_id | xpath://*[text(), \" >> \"] |\n| `Page Should Contain Element` | ${locator_list} | | |\n| ${element} = | Get WebElement | xpath://*[text(), \" >> \"] | |\n| ${locator_list} = | `Create List` | css:div#div_id | ${element} |\n| `Page Should Contain Element` | ${locator_list} | | |\n\nChaining locators in new in SeleniumLibrary 5.0\n\n== Using WebElements ==\n\nIn addition to specifying a locator as a string, it is possible to use\nSelenium's WebElement objects. This requires first getting a WebElement,\nfor example, by using the `Get WebElement` keyword.\n\n| ${elem} = | `Get WebElement` | id:example |\n| `Click Element` | ${elem} | |\n\n== Custom locators ==\n\nIf more complex lookups are required than what is provided through the\ndefault locators, custom lookup strategies can be created. Using custom\nlocators is a two part process. First, create a keyword that returns\na WebElement that should be acted on:\n\n| Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} |\n| | ${element}= | Execute Javascript | return window.document.getElementById('${locator}'); |\n| | [Return] | ${element} |\n\nThis keyword is a reimplementation of the basic functionality of the\n``id`` locator where ``${browser}`` is a reference to a WebDriver\ninstance and ``${locator}`` is the name of the locator strategy. To use\nthis locator, it must first be registered by using the\n`Add Location Strategy` keyword:\n\n| `Add Location Strategy` | custom | Custom Locator Strategy |\n\nThe first argument of `Add Location Strategy` specifies the name of\nthe strategy and it must be unique. After registering the strategy,\nthe usage is the same as with other locators:\n\n| `Click Element` | custom:example |\n\nSee the `Add Location Strategy` keyword for more details.\n\n= Browser and Window =\n\nThere is different conceptual meaning when SeleniumLibrary talks\nabout windows or browsers. This chapter explains those differences.\n\n== Browser ==\n\nWhen `Open Browser` or `Create WebDriver` keyword is called, it\nwill create a new Selenium WebDriver instance by using the\n[https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver]\nAPI. In SeleniumLibrary terms, a new browser is created. It is\npossible to start multiple independent browsers (Selenium Webdriver\ninstances) at the same time, by calling `Open Browser` or\n`Create WebDriver` multiple times. These browsers are usually\nindependent of each other and do not share data like cookies,\nsessions or profiles. Typically when the browser starts, it\ncreates a single window which is shown to the user.\n\n== Window ==\n\nWindows are the part of a browser that loads the web site and presents\nit to the user. All content of the site is the content of the window.\nWindows are children of a browser. In SeleniumLibrary browser is a\nsynonym for WebDriver instance. One browser may have multiple\nwindows. Windows can appear as tabs, as separate windows or pop-ups with\ndifferent position and size. Windows belonging to the same browser\ntypically share the sessions detail, like cookies. If there is a\nneed to separate sessions detail, example login with two different\nusers, two browsers (Selenium WebDriver instances) must be created.\nNew windows can be opened example by the application under test or\nby example `Execute Javascript` keyword:\n\n| `Execute Javascript` window.open() # Opens a new window with location about:blank\n\nThe example below opens multiple browsers and windows,\nto demonstrate how the different keywords can be used to interact\nwith browsers, and windows attached to these browsers.\n\nStructure:\n| BrowserA\n| Window 1 (location=https://robotframework.org/)\n| Window 2 (location=https://robocon.io/)\n| Window 3 (location=https://github.com/robotframework/)\n|\n| BrowserB\n| Window 1 (location=https://github.com/)\n\nExample:\n| `Open Browser` | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. |\n| `Execute Javascript` | window.open() | | | # In BrowserA second window is opened. |\n| `Switch Window` | locator=NEW | | | # Switched to second window in BrowserA |\n| `Go To` | https://robocon.io | | | # Second window navigates to robocon site. |\n| `Execute Javascript` | window.open() | | | # In BrowserA third window is opened. |\n| ${handle} | `Switch Window` | locator=NEW | | # Switched to third window in BrowserA |\n| `Go To` | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. |\n| `Open Browser` | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. |\n| ${location} | `Get Location` | | | # ${location} is: https://www.github.com |\n| `Switch Window` | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. |\n| ${location} | `Get Location` | | | # ${location} = https://robocon.io/ |\n| @{locations 1} | `Get Locations` | | | # By default, lists locations under the currectly active browser (BrowserA). |\n| @{locations 2} | `Get Locations` | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. |\n\nThe above example, @{locations 1} contains the following items:\nhttps://robotframework.org/, https://robocon.io/ and\nhttps://github.com/robotframework/'. The @{locations 2}\ncontains the following items: https://robotframework.org/,\nhttps://robocon.io/, https://github.com/robotframework/'\nand 'https://github.com/.\n\n= Browser and Driver options and service class =\n\nThis section talks about how to configure either the browser or\nthe driver using the options and service arguments of the `Open\nBrowser` keyword.\n\n== Configuring the browser using the Selenium Options ==\n\nAs noted within the keyword documentation for `Open Browser`, its\n``options`` argument accepts Selenium options in two different\nformats: as a string and as Python object which is an instance of\nthe Selenium options class.\n\n=== Options string format ===\n\nThe string format allows defining Selenium options methods\nor attributes and their arguments in Robot Framework test data.\nThe method and attributes names are case and space sensitive and\nmust match to the Selenium options methods and attributes names.\nWhen defining a method, it must be defined in a similar way as in\npython: method name, opening parenthesis, zero to many arguments\nand closing parenthesis. If there is a need to define multiple\narguments for a single method, arguments must be separated with\ncomma, just like in Python. Example: `add_argument(\"--headless\")`\nor `add_experimental_option(\"key\", \"value\")`. Attributes are\ndefined in a similar way as in Python: attribute name, equal sign,\nand attribute value. Example, `headless=True`. Multiple methods\nand attributes must be separated by a semicolon. Example:\n`add_argument(\"--headless\");add_argument(\"--start-maximized\")`.\n\nArguments allow defining Python data types and arguments are\nevaluated by using Python\n[https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].\nStrings must be quoted with single or double quotes, example \"value\"\nor 'value'. It is also possible to define other Python builtin\ndata types, example `True` or `None`, by not using quotes\naround the arguments.\n\nThe string format is space friendly. Usually, spaces do not alter\nthe defining methods or attributes. There are two exceptions.\nIn some Robot Framework test data formats, two or more spaces are\nconsidered as cell separator and instead of defining a single\nargument, two or more arguments may be defined. Spaces in string\narguments are not removed and are left as is. Example\n`add_argument ( \"--headless\" )` is same as\n`add_argument(\"--headless\")`. But `add_argument(\" --headless \")` is\nnot same same as `add_argument ( \"--headless\" )`, because\nspaces inside of quotes are not removed. Please note that if\noptions string contains backslash, example a Windows OS path,\nthe backslash needs escaping both in Robot Framework data and\nin Python side. This means single backslash must be writen using\nfour backslash characters. Example, Windows path:\n\"C:\\path\\to\\profile\" must be written as\n\"C:\\\\\\\\path\\\\\\to\\\\\\\\profile\". Another way to write\nbackslash is use Python\n[https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]\nand example write: r\"C:\\\\path\\\\to\\\\profile\".\n\n=== Selenium Options as Python class ===\n\nAs last format, ``options`` argument also supports receiving\nthe Selenium options as Python class instance. In this case, the\ninstance is used as-is and the SeleniumLibrary will not convert\nthe instance to other formats.\nFor example, if the following code return value is saved to\n`${options}` variable in the Robot Framework data:\n| options = webdriver.ChromeOptions()\n| options.add_argument('--disable-dev-shm-usage')\n| return options\n\nThen the `${options}` variable can be used as an argument to\n``options``.\n\nExample the ``options`` argument can be used to launch Chomium-based\napplications which utilize the\n[https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]\n. To launch Chromium-based application, use ``options`` to define\n`binary_location` attribute and use `add_argument` method to define\n`remote-debugging-port` port for the application. Once the browser\nis opened, the test can interact with the embedded web-content of\nthe system under test.\n\n== Configuring the driver using the Service class ==\n\nWith the ``service`` argument, one can setup and configure the driver. For example\none can set the driver location and/port or specify the command line arguments. There\nare several browser specific attributes related to logging as well. For the various\nService Class attributes refer to\n[https://www.selenium.dev/documentation/webdriver/drivers/service/|the Selenium documentation]\n. Currently the ``service`` argument only accepts Selenium service in the string format.\n\n=== Service string format ===\n\nThe string format allows for defining Selenium service attributes\nand their values in the `Open Browser` keyword. The attributes names\nare case and space sensitive and must match to the Selenium attributes\nnames. Attributes are defined in a similar way as in Python: attribute\nname, equal sign, and attribute value. Example, `port=1234`. Multiple\nattributes must be separated by a semicolon. Example:\n`executable_path='/path/to/driver';port=1234`. Don't have duplicate\nattributes, like `service_args=['--append-log', '--readable-timestamp'];\nservice_args=['--log-level=DEBUG']` as the second will override the first.\nInstead combine them as in\n`service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']`\n\nArguments allow defining Python data types and arguments are\nevaluated by using Python. Strings must be quoted with single\nor double quotes, example \"value\" or 'value'\n\n= Timeouts, waits, and delays =\n\nThis section discusses different ways how to wait for elements to\nappear on web pages and to slow down execution speed otherwise.\nIt also explains the `time format` that can be used when setting various\ntimeouts, waits, and delays.\n\n== Timeout ==\n\nSeleniumLibrary contains various keywords that have an optional\n``timeout`` argument that specifies how long these keywords should\nwait for certain events or actions. These keywords include, for example,\n``Wait ...`` keywords and keywords related to alerts. Additionally\n`Execute Async Javascript`. Although it does not have ``timeout``,\nargument, uses a timeout to define how long asynchronous JavaScript\ncan run.\n\nThe default timeout these keywords use can be set globally either by\nusing the `Set Selenium Timeout` keyword or with the ``timeout`` argument\nwhen `importing` the library. If no default timeout is set globally, the\ndefault is 5 seconds. If None is specified for the timeout argument in the\nkeywords, the default is used. See `time format` below for supported\ntimeout syntax.\n\n== Implicit wait ==\n\nImplicit wait specifies the maximum time how long Selenium waits when\nsearching for elements. It can be set by using the `Set Selenium Implicit\nWait` keyword or with the ``implicit_wait`` argument when `importing`\nthe library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp|\nSelenium documentation] for more information about this functionality.\n\nSee `time format` below for supported syntax.\n\n== Page load ==\nPage load timeout is the amount of time to wait for page load to complete\nuntil a timeout exception is raised.\n\nThe default page load timeout can be set globally\nwhen `importing` the library with the ``page_load_timeout`` argument\nor by using the `Set Selenium Page Load Timeout` keyword.\n\nSee `time format` below for supported timeout syntax.\n\nSupport for page load is new in SeleniumLibrary 6.1\n\n== Selenium speed ==\n\nSelenium execution speed can be slowed down globally by using `Set\nSelenium speed` keyword. This functionality is designed to be used for\ndemonstrating or debugging purposes. Using it to make sure that elements\nappear on a page is not a good idea. The above-explained timeouts\nand waits should be used instead.\n\nSee `time format` below for supported syntax.\n\n== Time format ==\n\nAll timeouts and waits can be given as numbers considered seconds\n(e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax\n(e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about\nthe time syntax see the\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide].\n\n= Run-on-failure functionality =\n\nSeleniumLibrary has a handy feature that it can automatically execute\na keyword if any of its own keywords fails. By default, it uses the\n`Capture Page Screenshot` keyword, but this can be changed either by\nusing the `Register Keyword To Run On Failure` keyword or with the\n``run_on_failure`` argument when `importing` the library. It is\npossible to use any keyword from any imported library or resource file.\n\nThe run-on-failure functionality can be disabled by using a special value\n``NOTHING`` or anything considered false (see `Boolean arguments`)\nsuch as ``NONE``.\n\n= Boolean arguments =\n\nStarting from 5.0 SeleniumLibrary relies on Robot Framework to perform the\nboolean conversion based on keyword arguments [https://docs.python.org/3/library/typing.html|type hint].\nMore details in Robot Framework\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#supported-conversions|user guide]\n\nPlease note SeleniumLibrary 3 and 4 did have own custom methods to covert\narguments to boolean values.\n\n= EventFiringWebDriver =\n\nThe SeleniumLibrary offers support for\n[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver].\nSee the Selenium and SeleniumLibrary\n[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#EventFiringWebDriver|EventFiringWebDriver support]\ndocumentation for further details.\n\nEventFiringWebDriver is new in SeleniumLibrary 4.0\n\n= Thread support =\n\nSeleniumLibrary is not thread-safe. This is mainly due because the underlying\n[https://github.com/SeleniumHQ/selenium/wiki/Frequently-Asked-Questions#q-is-webdriver-thread-safe|\nSelenium tool is not thread-safe] within one browser/driver instance.\nBecause of the limitation in the Selenium side, the keywords or the\nAPI provided by the SeleniumLibrary is not thread-safe.\n\n= Plugins =\n\nSeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal\nfunctionality without creating a new library or hacking the source code. See\n[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#Plugins|plugin API]\ndocumentation for further details.\n\nPlugin API is new SeleniumLibrary 4.0\n\n= Language =\n\nSeleniumLibrary offers the possibility to translate keyword names and documentation to new language. If language\nis defined, SeleniumLibrary will search from\n[https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path | module search path]\nfor Python packages starting with `robotframework-seleniumlibrary-translation` by using the\n[https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/ | Python pluging API]. The Library\nis using naming convention to find Python plugins.\n\nThe package must implement a single API call, ``get_language`` without any arguments. The method must return a\ndictionary containing two keys: ``language`` and ``path``. The language key value defines which language\nthe package contains. Also the value should match (case insensitive) the library ``language`` import parameter.\nThe path parameter value should be full path to the translation file.\n\n== Translation file ==\n\nThe file name or extension is not important, but data must be in [https://www.json.org/json-en.html | json]\nformat. The keys of json are the methods names, not the keyword names, which implements keywords. Value of\nkey is json object which contains two keys: ``name`` and ``doc``. The ``name`` key contains the keyword\ntranslated name and `doc` contains translated documentation. Providing doc and name are optional, example\ntranslation json file can only provide translations to keyword names or only to documentation. But it is\nalways recommended to provide translation to both name and doc. Special key ``__intro__`` is for class level\ndocumentation and ``__init__`` is for init level documentation. These special values ``name`` can not be\ntranslated, instead ``name`` should be kept the same.\n\n== Generating template translation file ==\n\nTemplate translation file, with English language can be created by running:\n`rfselib translation /path/to/translation.json` command. Command does not provide translations to other\nlanguages, it only provides easy way to create full list keywords and their documentation in correct\nformat. It is also possible to add keywords from library plugins by providing `--plugins` arguments\nto command. Example: `rfselib translation --plugins myplugin.SomePlugin /path/to/translation.json` The\ngenerated json file contains `sha256` key, which contains the sha256 sum of the library documentation.\nThe sha256 sum is used by `rfselib translation --compare /path/to/translation.json` command, which compares\nthe translation to the library and prints outs a table which tells if there are changes needed for\nthe translation file.\n\nExample project for translation can be found from\n[https://github.com/MarketSquare/robotframework-seleniumlibrary-translation-fi | robotframework-seleniumlibrary-translation-fi]\nrepository.", - "sha256": "affae82a074496d7c43327c8d44b332fbe455428f28b672c44e323e44d076f19" + "doc": "SeleniumLibrary is a web testing library for Robot Framework.\n\nThis document explains how to use keywords provided by SeleniumLibrary.\nFor information about installation, support, and more, please visit the\n[https://github.com/robotframework/SeleniumLibrary|project pages].\nFor more information about Robot Framework, see http://robotframework.org.\n\nSeleniumLibrary uses the Selenium WebDriver modules internally to\ncontrol a web browser. See http://seleniumhq.org for more information\nabout Selenium in general and SeleniumLibrary README.rst\n[https://github.com/robotframework/SeleniumLibrary#browser-drivers|Browser drivers chapter]\nfor more details about WebDriver binary installation.\n\n%TOC%\n\n= Locating elements =\n\nAll keywords in SeleniumLibrary that need to interact with an element\non a web page take an argument typically named ``locator`` that specifies\nhow to find the element. Most often the locator is given as a string\nusing the locator syntax described below, but `using WebElements` is\npossible too.\n\n== Locator syntax ==\n\nSeleniumLibrary supports finding elements based on different strategies\nsuch as the element id, XPath expressions, or CSS selectors. The strategy\ncan either be explicitly specified with a prefix or the strategy can be\nimplicit.\n\n=== Default locator strategy ===\n\nBy default, locators are considered to use the keyword specific default\nlocator strategy. All keywords support finding elements based on ``id``\nand ``name`` attributes, but some keywords support additional attributes\nor other values that make sense in their context. For example, `Click\nLink` supports the ``href`` attribute and the link text and addition\nto the normal ``id`` and ``name``.\n\nExamples:\n\n| `Click Element` | example | # Match based on ``id`` or ``name``. |\n| `Click Link` | example | # Match also based on link text and ``href``. |\n| `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. |\n\nIf a locator accidentally starts with a prefix recognized as `explicit\nlocator strategy` or `implicit XPath strategy`, it is possible to use\nthe explicit ``default`` prefix to enable the default strategy.\n\nExamples:\n\n| `Click Element` | name:foo | # Find element with name ``foo``. |\n| `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. |\n| `Click Element` | //foo | # Find element using XPath ``//foo``. |\n| `Click Element` | default: //foo | # Use default strategy with value ``//foo``. |\n\n=== Explicit locator strategy ===\n\nThe explicit locator strategy is specified with a prefix using either\nsyntax ``strategy:value`` or ``strategy=value``. The former syntax\nis preferred because the latter is identical to Robot Framework's\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax|\nnamed argument syntax] and that can cause problems. Spaces around\nthe separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo``\nare all equivalent.\n\nLocator strategies that are supported by default are listed in the table\nbelow. In addition to them, it is possible to register `custom locators`.\n\n| = Strategy = | = Match based on = | = Example = |\n| id | Element ``id``. | ``id:example`` |\n| name | ``name`` attribute. | ``name:example`` |\n| identifier | Either ``id`` or ``name``. | ``identifier:example`` |\n| class | Element ``class``. | ``class:example`` |\n| tag | Tag name. | ``tag:div`` |\n| xpath | XPath expression. | ``xpath://div[@id=\"example\"]`` |\n| css | CSS selector. | ``css:div#example`` |\n| dom | DOM expression. | ``dom:document.images[5]`` |\n| link | Exact text a link has. | ``link:The example`` |\n| partial link | Partial link text. | ``partial link:he ex`` |\n| sizzle | Sizzle selector deprecated. | ``sizzle:div.example`` |\n| data | Element ``data-*`` attribute | ``data:id:my_id`` |\n| jquery | jQuery expression. | ``jquery:div.example`` |\n| default | Keyword specific default behavior. | ``default:example`` |\n\nSee the `Default locator strategy` section below for more information\nabout how the default strategy works. Using the explicit ``default``\nprefix is only necessary if the locator value itself accidentally\nmatches some of the explicit strategies.\n\nDifferent locator strategies have different pros and cons. Using ids,\neither explicitly like ``id:foo`` or by using the `default locator\nstrategy` simply like ``foo``, is recommended when possible, because\nthe syntax is simple and locating elements by id is fast for browsers.\nIf an element does not have an id or the id is not stable, other\nsolutions need to be used. If an element has a unique tag name or class,\nusing ``tag``, ``class`` or ``css`` strategy like ``tag:h1``,\n``class:example`` or ``css:h1.example`` is often an easy solution. In\nmore complex cases using XPath expressions is typically the best\napproach. They are very powerful but a downside is that they can also\nget complex.\n\nExamples:\n\n| `Click Element` | id:foo | # Element with id 'foo'. |\n| `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. |\n| `Click Element` | xpath: //div[@id=\"foo\"]//h1 | # Same as the above using XPath, not CSS. |\n| `Click Element` | xpath: //*[contains(text(), \"example\")] | # Element containing text 'example'. |\n\n*NOTE:*\n\n- The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0\n and newer.\n- Using the ``sizzle`` strategy or its alias ``jquery`` requires that\n the system under test contains the jQuery library.\n- Prior to SeleniumLibrary 3.0, table related keywords only supported\n ``xpath``, ``css`` and ``sizzle/jquery`` strategies.\n- ``data`` strategy is conveniance locator that will construct xpath from the parameters.\n If you have element like `
`, you locate the element via\n ``data:automation:automation-id-2``. This feature was added in SeleniumLibrary 5.2.0\n\n=== Implicit XPath strategy ===\n\nIf the locator starts with ``//`` or multiple opening parenthesis in front\nof the ``//``, the locator is considered to be an XPath expression. In other\nwords, using ``//div`` is equivalent to using explicit ``xpath://div`` and\n``((//div))`` is equivalent to using explicit ``xpath:((//div))``\n\nExamples:\n\n| `Click Element` | //div[@id=\"foo\"]//h1 |\n| `Click Element` | (//div)[2] |\n\nThe support for the ``(//`` prefix is new in SeleniumLibrary 3.0.\nSupporting multiple opening parenthesis is new in SeleniumLibrary 5.0.\n\n=== Chaining locators ===\n\nIt is possible chain multiple locators together as single locator. Each chained locator must start with locator\nstrategy. Chained locators must be separated with single space, two greater than characters and followed with\nspace. It is also possible mix different locator strategies, example css or xpath. Also a list can also be\nused to specify multiple locators. This is useful, is some part of locator would match as the locator separator\nbut it should not. Or if there is need to existing WebElement as locator.\n\nAlthough all locators support chaining, some locator strategies do not abey the chaining. This is because\nsome locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context\nand not for the element found be the previous locator. Chaining is supported by locator strategies which\nare based on Selenium API, like `xpath` or `css`, but example chaining is not supported by `sizzle` or `jquery\n\nExamples:\n| `Click Element` | css:.bar >> xpath://a | # To find a link which is present after an element with class \"bar\" |\n\nList examples:\n| ${locator_list} = | `Create List` | css:div#div_id | xpath://*[text(), \" >> \"] |\n| `Page Should Contain Element` | ${locator_list} | | |\n| ${element} = | Get WebElement | xpath://*[text(), \" >> \"] | |\n| ${locator_list} = | `Create List` | css:div#div_id | ${element} |\n| `Page Should Contain Element` | ${locator_list} | | |\n\nChaining locators in new in SeleniumLibrary 5.0\n\n== Using WebElements ==\n\nIn addition to specifying a locator as a string, it is possible to use\nSelenium's WebElement objects. This requires first getting a WebElement,\nfor example, by using the `Get WebElement` keyword.\n\n| ${elem} = | `Get WebElement` | id:example |\n| `Click Element` | ${elem} | |\n\n== Custom locators ==\n\nIf more complex lookups are required than what is provided through the\ndefault locators, custom lookup strategies can be created. Using custom\nlocators is a two part process. First, create a keyword that returns\na WebElement that should be acted on:\n\n| Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} |\n| | ${element}= | Execute Javascript | return window.document.getElementById('${locator}'); |\n| | RETURN | ${element} |\n\nThis keyword is a reimplementation of the basic functionality of the\n``id`` locator where ``${browser}`` is a reference to a WebDriver\ninstance and ``${locator}`` is the name of the locator strategy. To use\nthis locator, it must first be registered by using the\n`Add Location Strategy` keyword:\n\n| `Add Location Strategy` | custom | Custom Locator Strategy |\n\nThe first argument of `Add Location Strategy` specifies the name of\nthe strategy and it must be unique. After registering the strategy,\nthe usage is the same as with other locators:\n\n| `Click Element` | custom:example |\n\nSee the `Add Location Strategy` keyword for more details.\n\n= Browser and Window =\n\nThere is different conceptual meaning when SeleniumLibrary talks\nabout windows or browsers. This chapter explains those differences.\n\n== Browser ==\n\nWhen `Open Browser` or `Create WebDriver` keyword is called, it\nwill create a new Selenium WebDriver instance by using the\n[https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver]\nAPI. In SeleniumLibrary terms, a new browser is created. It is\npossible to start multiple independent browsers (Selenium Webdriver\ninstances) at the same time, by calling `Open Browser` or\n`Create WebDriver` multiple times. These browsers are usually\nindependent of each other and do not share data like cookies,\nsessions or profiles. Typically when the browser starts, it\ncreates a single window which is shown to the user.\n\n== Window ==\n\nWindows are the part of a browser that loads the web site and presents\nit to the user. All content of the site is the content of the window.\nWindows are children of a browser. In SeleniumLibrary browser is a\nsynonym for WebDriver instance. One browser may have multiple\nwindows. Windows can appear as tabs, as separate windows or pop-ups with\ndifferent position and size. Windows belonging to the same browser\ntypically share the sessions detail, like cookies. If there is a\nneed to separate sessions detail, example login with two different\nusers, two browsers (Selenium WebDriver instances) must be created.\nNew windows can be opened example by the application under test or\nby example `Execute Javascript` keyword:\n\n| `Execute Javascript` window.open() # Opens a new window with location about:blank\n\nThe example below opens multiple browsers and windows,\nto demonstrate how the different keywords can be used to interact\nwith browsers, and windows attached to these browsers.\n\nStructure:\n| BrowserA\n| Window 1 (location=https://robotframework.org/)\n| Window 2 (location=https://robocon.io/)\n| Window 3 (location=https://github.com/robotframework/)\n|\n| BrowserB\n| Window 1 (location=https://github.com/)\n\nExample:\n| `Open Browser` | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. |\n| `Execute Javascript` | window.open() | | | # In BrowserA second window is opened. |\n| `Switch Window` | locator=NEW | | | # Switched to second window in BrowserA |\n| `Go To` | https://robocon.io | | | # Second window navigates to robocon site. |\n| `Execute Javascript` | window.open() | | | # In BrowserA third window is opened. |\n| ${handle} | `Switch Window` | locator=NEW | | # Switched to third window in BrowserA |\n| `Go To` | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. |\n| `Open Browser` | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. |\n| ${location} | `Get Location` | | | # ${location} is: https://www.github.com |\n| `Switch Window` | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. |\n| ${location} | `Get Location` | | | # ${location} = https://robocon.io/ |\n| @{locations 1} | `Get Locations` | | | # By default, lists locations under the currectly active browser (BrowserA). |\n| @{locations 2} | `Get Locations` | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. |\n\nThe above example, @{locations 1} contains the following items:\nhttps://robotframework.org/, https://robocon.io/ and\nhttps://github.com/robotframework/'. The @{locations 2}\ncontains the following items: https://robotframework.org/,\nhttps://robocon.io/, https://github.com/robotframework/'\nand 'https://github.com/.\n\n= Browser and Driver options and service class =\n\nThis section talks about how to configure either the browser or\nthe driver using the options and service arguments of the `Open\nBrowser` keyword.\n\n== Configuring the browser using the Selenium Options ==\n\nAs noted within the keyword documentation for `Open Browser`, its\n``options`` argument accepts Selenium options in two different\nformats: as a string and as Python object which is an instance of\nthe Selenium options class.\n\n=== Options string format ===\n\nThe string format allows defining Selenium options methods\nor attributes and their arguments in Robot Framework test data.\nThe method and attributes names are case and space sensitive and\nmust match to the Selenium options methods and attributes names.\nWhen defining a method, it must be defined in a similar way as in\npython: method name, opening parenthesis, zero to many arguments\nand closing parenthesis. If there is a need to define multiple\narguments for a single method, arguments must be separated with\ncomma, just like in Python. Example: `add_argument(\"--headless\")`\nor `add_experimental_option(\"key\", \"value\")`. Attributes are\ndefined in a similar way as in Python: attribute name, equal sign,\nand attribute value. Example, `headless=True`. Multiple methods\nand attributes must be separated by a semicolon. Example:\n`add_argument(\"--headless\");add_argument(\"--start-maximized\")`.\n\nArguments allow defining Python data types and arguments are\nevaluated by using Python\n[https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].\nStrings must be quoted with single or double quotes, example \"value\"\nor 'value'. It is also possible to define other Python builtin\ndata types, example `True` or `None`, by not using quotes\naround the arguments.\n\nThe string format is space friendly. Usually, spaces do not alter\nthe defining methods or attributes. There are two exceptions.\nIn some Robot Framework test data formats, two or more spaces are\nconsidered as cell separator and instead of defining a single\nargument, two or more arguments may be defined. Spaces in string\narguments are not removed and are left as is. Example\n`add_argument ( \"--headless\" )` is same as\n`add_argument(\"--headless\")`. But `add_argument(\" --headless \")` is\nnot same same as `add_argument ( \"--headless\" )`, because\nspaces inside of quotes are not removed. Please note that if\noptions string contains backslash, example a Windows OS path,\nthe backslash needs escaping both in Robot Framework data and\nin Python side. This means single backslash must be writen using\nfour backslash characters. Example, Windows path:\n\"C:\\path\\to\\profile\" must be written as\n\"C:\\\\\\\\path\\\\\\to\\\\\\\\profile\". Another way to write\nbackslash is use Python\n[https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]\nand example write: r\"C:\\\\path\\\\to\\\\profile\".\n\n=== Selenium Options as Python class ===\n\nAs last format, ``options`` argument also supports receiving\nthe Selenium options as Python class instance. In this case, the\ninstance is used as-is and the SeleniumLibrary will not convert\nthe instance to other formats.\nFor example, if the following code return value is saved to\n`${options}` variable in the Robot Framework data:\n| options = webdriver.ChromeOptions()\n| options.add_argument('--disable-dev-shm-usage')\n| return options\n\nThen the `${options}` variable can be used as an argument to\n``options``.\n\nExample the ``options`` argument can be used to launch Chomium-based\napplications which utilize the\n[https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]\n. To launch Chromium-based application, use ``options`` to define\n`binary_location` attribute and use `add_argument` method to define\n`remote-debugging-port` port for the application. Once the browser\nis opened, the test can interact with the embedded web-content of\nthe system under test.\n\n== Configuring the driver using the Service class ==\n\nWith the ``service`` argument, one can setup and configure the driver. For example\none can set the driver location and/port or specify the command line arguments. There\nare several browser specific attributes related to logging as well. For the various\nService Class attributes refer to\n[https://www.selenium.dev/documentation/webdriver/drivers/service/|the Selenium documentation]\n. Currently the ``service`` argument only accepts Selenium service in the string format.\n\n=== Service string format ===\n\nThe string format allows for defining Selenium service attributes\nand their values in the `Open Browser` keyword. The attributes names\nare case and space sensitive and must match to the Selenium attributes\nnames. Attributes are defined in a similar way as in Python: attribute\nname, equal sign, and attribute value. Example, `port=1234`. Multiple\nattributes must be separated by a semicolon. Example:\n`executable_path='/path/to/driver';port=1234`. Don't have duplicate\nattributes, like `service_args=['--append-log', '--readable-timestamp'];\nservice_args=['--log-level=DEBUG']` as the second will override the first.\nInstead combine them as in\n`service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']`\n\nArguments allow defining Python data types and arguments are\nevaluated by using Python. Strings must be quoted with single\nor double quotes, example \"value\" or 'value'\n\n= Timeouts, waits, and delays =\n\nThis section discusses different ways how to wait for elements to\nappear on web pages and to slow down execution speed otherwise.\nIt also explains the `time format` that can be used when setting various\ntimeouts, waits, and delays.\n\n== Timeout ==\n\nSeleniumLibrary contains various keywords that have an optional\n``timeout`` argument that specifies how long these keywords should\nwait for certain events or actions. These keywords include, for example,\n``Wait ...`` keywords and keywords related to alerts. Additionally\n`Execute Async Javascript`. Although it does not have ``timeout``,\nargument, uses a timeout to define how long asynchronous JavaScript\ncan run.\n\nThe default timeout these keywords use can be set globally either by\nusing the `Set Selenium Timeout` keyword or with the ``timeout`` argument\nwhen `importing` the library. If no default timeout is set globally, the\ndefault is 5 seconds. If None is specified for the timeout argument in the\nkeywords, the default is used. See `time format` below for supported\ntimeout syntax.\n\n== Implicit wait ==\n\nImplicit wait specifies the maximum time how long Selenium waits when\nsearching for elements. It can be set by using the `Set Selenium Implicit\nWait` keyword or with the ``implicit_wait`` argument when `importing`\nthe library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp|\nSelenium documentation] for more information about this functionality.\n\nSee `time format` below for supported syntax.\n\n== Page load ==\nPage load timeout is the amount of time to wait for page load to complete\nuntil a timeout exception is raised.\n\nThe default page load timeout can be set globally\nwhen `importing` the library with the ``page_load_timeout`` argument\nor by using the `Set Selenium Page Load Timeout` keyword.\n\nSee `time format` below for supported timeout syntax.\n\nSupport for page load is new in SeleniumLibrary 6.1\n\n== Selenium speed ==\n\nSelenium execution speed can be slowed down globally by using `Set\nSelenium speed` keyword. This functionality is designed to be used for\ndemonstrating or debugging purposes. Using it to make sure that elements\nappear on a page is not a good idea. The above-explained timeouts\nand waits should be used instead.\n\nSee `time format` below for supported syntax.\n\n== Time format ==\n\nAll timeouts and waits can be given as numbers considered seconds\n(e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax\n(e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about\nthe time syntax see the\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide].\n\n= Run-on-failure functionality =\n\nSeleniumLibrary has a handy feature that it can automatically execute\na keyword if any of its own keywords fails. By default, it uses the\n`Capture Page Screenshot` keyword, but this can be changed either by\nusing the `Register Keyword To Run On Failure` keyword or with the\n``run_on_failure`` argument when `importing` the library. It is\npossible to use any keyword from any imported library or resource file.\n\nThe run-on-failure functionality can be disabled by using a special value\n``NOTHING`` or anything considered false (see `Boolean arguments`)\nsuch as ``NONE``.\n\n= Boolean arguments =\n\nStarting from 5.0 SeleniumLibrary relies on Robot Framework to perform the\nboolean conversion based on keyword arguments [https://docs.python.org/3/library/typing.html|type hint].\nMore details in Robot Framework\n[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#supported-conversions|user guide]\n\nPlease note SeleniumLibrary 3 and 4 did have own custom methods to covert\narguments to boolean values.\n\n= EventFiringWebDriver =\n\nThe SeleniumLibrary offers support for\n[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver].\nSee the Selenium and SeleniumLibrary\n[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#EventFiringWebDriver|EventFiringWebDriver support]\ndocumentation for further details.\n\nEventFiringWebDriver is new in SeleniumLibrary 4.0\n\n= Thread support =\n\nSeleniumLibrary is not thread-safe. This is mainly due because the underlying\n[https://github.com/SeleniumHQ/selenium/wiki/Frequently-Asked-Questions#q-is-webdriver-thread-safe|\nSelenium tool is not thread-safe] within one browser/driver instance.\nBecause of the limitation in the Selenium side, the keywords or the\nAPI provided by the SeleniumLibrary is not thread-safe.\n\n= Plugins =\n\nSeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal\nfunctionality without creating a new library or hacking the source code. See\n[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#Plugins|plugin API]\ndocumentation for further details.\n\nPlugin API is new SeleniumLibrary 4.0\n\n= Language =\n\nSeleniumLibrary offers the possibility to translate keyword names and documentation to new language. If language\nis defined, SeleniumLibrary will search from\n[https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path | module search path]\nfor Python packages starting with `robotframework-seleniumlibrary-translation` by using the\n[https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/ | Python pluging API]. The Library\nis using naming convention to find Python plugins.\n\nThe package must implement a single API call, ``get_language`` without any arguments. The method must return a\ndictionary containing two keys: ``language`` and ``path``. The language key value defines which language\nthe package contains. Also the value should match (case insensitive) the library ``language`` import parameter.\nThe path parameter value should be full path to the translation file.\n\n== Translation file ==\n\nThe file name or extension is not important, but data must be in [https://www.json.org/json-en.html | json]\nformat. The keys of json are the methods names, not the keyword names, which implements keywords. Value of\nkey is json object which contains two keys: ``name`` and ``doc``. The ``name`` key contains the keyword\ntranslated name and `doc` contains translated documentation. Providing doc and name are optional, example\ntranslation json file can only provide translations to keyword names or only to documentation. But it is\nalways recommended to provide translation to both name and doc. Special key ``__intro__`` is for class level\ndocumentation and ``__init__`` is for init level documentation. These special values ``name`` can not be\ntranslated, instead ``name`` should be kept the same.\n\n== Generating template translation file ==\n\nTemplate translation file, with English language can be created by running:\n`rfselib translation /path/to/translation.json` command. Command does not provide translations to other\nlanguages, it only provides easy way to create full list keywords and their documentation in correct\nformat. It is also possible to add keywords from library plugins by providing `--plugins` arguments\nto command. Example: `rfselib translation --plugins myplugin.SomePlugin /path/to/translation.json` The\ngenerated json file contains `sha256` key, which contains the sha256 sum of the library documentation.\nThe sha256 sum is used by `rfselib translation --compare /path/to/translation.json` command, which compares\nthe translation to the library and prints outs a table which tells if there are changes needed for\nthe translation file.\n\nExample project for translation can be found from\n[https://github.com/MarketSquare/robotframework-seleniumlibrary-translation-fi | robotframework-seleniumlibrary-translation-fi]\nrepository.", + "sha256": "feaa9d9fe756a50f322190440e514ec6fa72d34f24749609287cf9ada5e8beac" }, "__intro__": { "name": "__intro__", - "doc": "SeleniumLibrary is a web testing library for Robot Framework.\n\n This document explains how to use keywords provided by SeleniumLibrary.\n For information about installation, support, and more, please visit the\n [https://github.com/robotframework/SeleniumLibrary|project pages].\n For more information about Robot Framework, see http://robotframework.org.\n\n SeleniumLibrary uses the Selenium WebDriver modules internally to\n control a web browser. See http://seleniumhq.org for more information\n about Selenium in general and SeleniumLibrary README.rst\n [https://github.com/robotframework/SeleniumLibrary#browser-drivers|Browser drivers chapter]\n for more details about WebDriver binary installation.\n\n %TOC%\n\n = Locating elements =\n\n All keywords in SeleniumLibrary that need to interact with an element\n on a web page take an argument typically named ``locator`` that specifies\n how to find the element. Most often the locator is given as a string\n using the locator syntax described below, but `using WebElements` is\n possible too.\n\n == Locator syntax ==\n\n SeleniumLibrary supports finding elements based on different strategies\n such as the element id, XPath expressions, or CSS selectors. The strategy\n can either be explicitly specified with a prefix or the strategy can be\n implicit.\n\n === Default locator strategy ===\n\n By default, locators are considered to use the keyword specific default\n locator strategy. All keywords support finding elements based on ``id``\n and ``name`` attributes, but some keywords support additional attributes\n or other values that make sense in their context. For example, `Click\n Link` supports the ``href`` attribute and the link text and addition\n to the normal ``id`` and ``name``.\n\n Examples:\n\n | `Click Element` | example | # Match based on ``id`` or ``name``. |\n | `Click Link` | example | # Match also based on link text and ``href``. |\n | `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. |\n\n If a locator accidentally starts with a prefix recognized as `explicit\n locator strategy` or `implicit XPath strategy`, it is possible to use\n the explicit ``default`` prefix to enable the default strategy.\n\n Examples:\n\n | `Click Element` | name:foo | # Find element with name ``foo``. |\n | `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. |\n | `Click Element` | //foo | # Find element using XPath ``//foo``. |\n | `Click Element` | default: //foo | # Use default strategy with value ``//foo``. |\n\n === Explicit locator strategy ===\n\n The explicit locator strategy is specified with a prefix using either\n syntax ``strategy:value`` or ``strategy=value``. The former syntax\n is preferred because the latter is identical to Robot Framework's\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax|\n named argument syntax] and that can cause problems. Spaces around\n the separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo``\n are all equivalent.\n\n Locator strategies that are supported by default are listed in the table\n below. In addition to them, it is possible to register `custom locators`.\n\n | = Strategy = | = Match based on = | = Example = |\n | id | Element ``id``. | ``id:example`` |\n | name | ``name`` attribute. | ``name:example`` |\n | identifier | Either ``id`` or ``name``. | ``identifier:example`` |\n | class | Element ``class``. | ``class:example`` |\n | tag | Tag name. | ``tag:div`` |\n | xpath | XPath expression. | ``xpath://div[@id=\"example\"]`` |\n | css | CSS selector. | ``css:div#example`` |\n | dom | DOM expression. | ``dom:document.images[5]`` |\n | link | Exact text a link has. | ``link:The example`` |\n | partial link | Partial link text. | ``partial link:he ex`` |\n | sizzle | Sizzle selector deprecated. | ``sizzle:div.example`` |\n | data | Element ``data-*`` attribute | ``data:id:my_id`` |\n | jquery | jQuery expression. | ``jquery:div.example`` |\n | default | Keyword specific default behavior. | ``default:example`` |\n\n See the `Default locator strategy` section below for more information\n about how the default strategy works. Using the explicit ``default``\n prefix is only necessary if the locator value itself accidentally\n matches some of the explicit strategies.\n\n Different locator strategies have different pros and cons. Using ids,\n either explicitly like ``id:foo`` or by using the `default locator\n strategy` simply like ``foo``, is recommended when possible, because\n the syntax is simple and locating elements by id is fast for browsers.\n If an element does not have an id or the id is not stable, other\n solutions need to be used. If an element has a unique tag name or class,\n using ``tag``, ``class`` or ``css`` strategy like ``tag:h1``,\n ``class:example`` or ``css:h1.example`` is often an easy solution. In\n more complex cases using XPath expressions is typically the best\n approach. They are very powerful but a downside is that they can also\n get complex.\n\n Examples:\n\n | `Click Element` | id:foo | # Element with id 'foo'. |\n | `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. |\n | `Click Element` | xpath: //div[@id=\"foo\"]//h1 | # Same as the above using XPath, not CSS. |\n | `Click Element` | xpath: //*[contains(text(), \"example\")] | # Element containing text 'example'. |\n\n *NOTE:*\n\n - The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0\n and newer.\n - Using the ``sizzle`` strategy or its alias ``jquery`` requires that\n the system under test contains the jQuery library.\n - Prior to SeleniumLibrary 3.0, table related keywords only supported\n ``xpath``, ``css`` and ``sizzle/jquery`` strategies.\n - ``data`` strategy is conveniance locator that will construct xpath from the parameters.\n If you have element like `
`, you locate the element via\n ``data:automation:automation-id-2``. This feature was added in SeleniumLibrary 5.2.0\n\n === Implicit XPath strategy ===\n\n If the locator starts with ``//`` or multiple opening parenthesis in front\n of the ``//``, the locator is considered to be an XPath expression. In other\n words, using ``//div`` is equivalent to using explicit ``xpath://div`` and\n ``((//div))`` is equivalent to using explicit ``xpath:((//div))``\n\n Examples:\n\n | `Click Element` | //div[@id=\"foo\"]//h1 |\n | `Click Element` | (//div)[2] |\n\n The support for the ``(//`` prefix is new in SeleniumLibrary 3.0.\n Supporting multiple opening parenthesis is new in SeleniumLibrary 5.0.\n\n === Chaining locators ===\n\n It is possible chain multiple locators together as single locator. Each chained locator must start with locator\n strategy. Chained locators must be separated with single space, two greater than characters and followed with\n space. It is also possible mix different locator strategies, example css or xpath. Also a list can also be\n used to specify multiple locators. This is useful, is some part of locator would match as the locator separator\n but it should not. Or if there is need to existing WebElement as locator.\n\n Although all locators support chaining, some locator strategies do not abey the chaining. This is because\n some locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context\n and not for the element found be the previous locator. Chaining is supported by locator strategies which\n are based on Selenium API, like `xpath` or `css`, but example chaining is not supported by `sizzle` or `jquery\n\n Examples:\n | `Click Element` | css:.bar >> xpath://a | # To find a link which is present after an element with class \"bar\" |\n\n List examples:\n | ${locator_list} = | `Create List` | css:div#div_id | xpath://*[text(), \" >> \"] |\n | `Page Should Contain Element` | ${locator_list} | | |\n | ${element} = | Get WebElement | xpath://*[text(), \" >> \"] | |\n | ${locator_list} = | `Create List` | css:div#div_id | ${element} |\n | `Page Should Contain Element` | ${locator_list} | | |\n\n Chaining locators in new in SeleniumLibrary 5.0\n\n == Using WebElements ==\n\n In addition to specifying a locator as a string, it is possible to use\n Selenium's WebElement objects. This requires first getting a WebElement,\n for example, by using the `Get WebElement` keyword.\n\n | ${elem} = | `Get WebElement` | id:example |\n | `Click Element` | ${elem} | |\n\n == Custom locators ==\n\n If more complex lookups are required than what is provided through the\n default locators, custom lookup strategies can be created. Using custom\n locators is a two part process. First, create a keyword that returns\n a WebElement that should be acted on:\n\n | Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} |\n | | ${element}= | Execute Javascript | return window.document.getElementById('${locator}'); |\n | | [Return] | ${element} |\n\n This keyword is a reimplementation of the basic functionality of the\n ``id`` locator where ``${browser}`` is a reference to a WebDriver\n instance and ``${locator}`` is the name of the locator strategy. To use\n this locator, it must first be registered by using the\n `Add Location Strategy` keyword:\n\n | `Add Location Strategy` | custom | Custom Locator Strategy |\n\n The first argument of `Add Location Strategy` specifies the name of\n the strategy and it must be unique. After registering the strategy,\n the usage is the same as with other locators:\n\n | `Click Element` | custom:example |\n\n See the `Add Location Strategy` keyword for more details.\n\n = Browser and Window =\n\n There is different conceptual meaning when SeleniumLibrary talks\n about windows or browsers. This chapter explains those differences.\n\n == Browser ==\n\n When `Open Browser` or `Create WebDriver` keyword is called, it\n will create a new Selenium WebDriver instance by using the\n [https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver]\n API. In SeleniumLibrary terms, a new browser is created. It is\n possible to start multiple independent browsers (Selenium Webdriver\n instances) at the same time, by calling `Open Browser` or\n `Create WebDriver` multiple times. These browsers are usually\n independent of each other and do not share data like cookies,\n sessions or profiles. Typically when the browser starts, it\n creates a single window which is shown to the user.\n\n == Window ==\n\n Windows are the part of a browser that loads the web site and presents\n it to the user. All content of the site is the content of the window.\n Windows are children of a browser. In SeleniumLibrary browser is a\n synonym for WebDriver instance. One browser may have multiple\n windows. Windows can appear as tabs, as separate windows or pop-ups with\n different position and size. Windows belonging to the same browser\n typically share the sessions detail, like cookies. If there is a\n need to separate sessions detail, example login with two different\n users, two browsers (Selenium WebDriver instances) must be created.\n New windows can be opened example by the application under test or\n by example `Execute Javascript` keyword:\n\n | `Execute Javascript` window.open() # Opens a new window with location about:blank\n\n The example below opens multiple browsers and windows,\n to demonstrate how the different keywords can be used to interact\n with browsers, and windows attached to these browsers.\n\n Structure:\n | BrowserA\n | Window 1 (location=https://robotframework.org/)\n | Window 2 (location=https://robocon.io/)\n | Window 3 (location=https://github.com/robotframework/)\n |\n | BrowserB\n | Window 1 (location=https://github.com/)\n\n Example:\n | `Open Browser` | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. |\n | `Execute Javascript` | window.open() | | | # In BrowserA second window is opened. |\n | `Switch Window` | locator=NEW | | | # Switched to second window in BrowserA |\n | `Go To` | https://robocon.io | | | # Second window navigates to robocon site. |\n | `Execute Javascript` | window.open() | | | # In BrowserA third window is opened. |\n | ${handle} | `Switch Window` | locator=NEW | | # Switched to third window in BrowserA |\n | `Go To` | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. |\n | `Open Browser` | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. |\n | ${location} | `Get Location` | | | # ${location} is: https://www.github.com |\n | `Switch Window` | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. |\n | ${location} | `Get Location` | | | # ${location} = https://robocon.io/ |\n | @{locations 1} | `Get Locations` | | | # By default, lists locations under the currectly active browser (BrowserA). |\n | @{locations 2} | `Get Locations` | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. |\n\n The above example, @{locations 1} contains the following items:\n https://robotframework.org/, https://robocon.io/ and\n https://github.com/robotframework/'. The @{locations 2}\n contains the following items: https://robotframework.org/,\n https://robocon.io/, https://github.com/robotframework/'\n and 'https://github.com/.\n\n = Browser and Driver options and service class =\n\n This section talks about how to configure either the browser or\n the driver using the options and service arguments of the `Open\n Browser` keyword.\n\n == Configuring the browser using the Selenium Options ==\n\n As noted within the keyword documentation for `Open Browser`, its\n ``options`` argument accepts Selenium options in two different\n formats: as a string and as Python object which is an instance of\n the Selenium options class.\n\n === Options string format ===\n\n The string format allows defining Selenium options methods\n or attributes and their arguments in Robot Framework test data.\n The method and attributes names are case and space sensitive and\n must match to the Selenium options methods and attributes names.\n When defining a method, it must be defined in a similar way as in\n python: method name, opening parenthesis, zero to many arguments\n and closing parenthesis. If there is a need to define multiple\n arguments for a single method, arguments must be separated with\n comma, just like in Python. Example: `add_argument(\"--headless\")`\n or `add_experimental_option(\"key\", \"value\")`. Attributes are\n defined in a similar way as in Python: attribute name, equal sign,\n and attribute value. Example, `headless=True`. Multiple methods\n and attributes must be separated by a semicolon. Example:\n `add_argument(\"--headless\");add_argument(\"--start-maximized\")`.\n\n Arguments allow defining Python data types and arguments are\n evaluated by using Python\n [https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].\n Strings must be quoted with single or double quotes, example \"value\"\n or 'value'. It is also possible to define other Python builtin\n data types, example `True` or `None`, by not using quotes\n around the arguments.\n\n The string format is space friendly. Usually, spaces do not alter\n the defining methods or attributes. There are two exceptions.\n In some Robot Framework test data formats, two or more spaces are\n considered as cell separator and instead of defining a single\n argument, two or more arguments may be defined. Spaces in string\n arguments are not removed and are left as is. Example\n `add_argument ( \"--headless\" )` is same as\n `add_argument(\"--headless\")`. But `add_argument(\" --headless \")` is\n not same same as `add_argument ( \"--headless\" )`, because\n spaces inside of quotes are not removed. Please note that if\n options string contains backslash, example a Windows OS path,\n the backslash needs escaping both in Robot Framework data and\n in Python side. This means single backslash must be writen using\n four backslash characters. Example, Windows path:\n \"C:\\path\\to\\profile\" must be written as\n \"C:\\\\\\\\path\\\\\\to\\\\\\\\profile\". Another way to write\n backslash is use Python\n [https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]\n and example write: r\"C:\\\\path\\\\to\\\\profile\".\n\n === Selenium Options as Python class ===\n\n As last format, ``options`` argument also supports receiving\n the Selenium options as Python class instance. In this case, the\n instance is used as-is and the SeleniumLibrary will not convert\n the instance to other formats.\n For example, if the following code return value is saved to\n `${options}` variable in the Robot Framework data:\n | options = webdriver.ChromeOptions()\n | options.add_argument('--disable-dev-shm-usage')\n | return options\n\n Then the `${options}` variable can be used as an argument to\n ``options``.\n\n Example the ``options`` argument can be used to launch Chomium-based\n applications which utilize the\n [https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]\n . To launch Chromium-based application, use ``options`` to define\n `binary_location` attribute and use `add_argument` method to define\n `remote-debugging-port` port for the application. Once the browser\n is opened, the test can interact with the embedded web-content of\n the system under test.\n\n == Configuring the driver using the Service class ==\n\n With the ``service`` argument, one can setup and configure the driver. For example\n one can set the driver location and/port or specify the command line arguments. There\n are several browser specific attributes related to logging as well. For the various\n Service Class attributes refer to\n [https://www.selenium.dev/documentation/webdriver/drivers/service/|the Selenium documentation]\n . Currently the ``service`` argument only accepts Selenium service in the string format.\n\n === Service string format ===\n\n The string format allows for defining Selenium service attributes\n and their values in the `Open Browser` keyword. The attributes names\n are case and space sensitive and must match to the Selenium attributes\n names. Attributes are defined in a similar way as in Python: attribute\n name, equal sign, and attribute value. Example, `port=1234`. Multiple\n attributes must be separated by a semicolon. Example:\n `executable_path='/path/to/driver';port=1234`. Don't have duplicate\n attributes, like `service_args=['--append-log', '--readable-timestamp'];\n service_args=['--log-level=DEBUG']` as the second will override the first.\n Instead combine them as in\n `service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']`\n\n Arguments allow defining Python data types and arguments are\n evaluated by using Python. Strings must be quoted with single\n or double quotes, example \"value\" or 'value'\n\n = Timeouts, waits, and delays =\n\n This section discusses different ways how to wait for elements to\n appear on web pages and to slow down execution speed otherwise.\n It also explains the `time format` that can be used when setting various\n timeouts, waits, and delays.\n\n == Timeout ==\n\n SeleniumLibrary contains various keywords that have an optional\n ``timeout`` argument that specifies how long these keywords should\n wait for certain events or actions. These keywords include, for example,\n ``Wait ...`` keywords and keywords related to alerts. Additionally\n `Execute Async Javascript`. Although it does not have ``timeout``,\n argument, uses a timeout to define how long asynchronous JavaScript\n can run.\n\n The default timeout these keywords use can be set globally either by\n using the `Set Selenium Timeout` keyword or with the ``timeout`` argument\n when `importing` the library. If no default timeout is set globally, the\n default is 5 seconds. If None is specified for the timeout argument in the\n keywords, the default is used. See `time format` below for supported\n timeout syntax.\n\n == Implicit wait ==\n\n Implicit wait specifies the maximum time how long Selenium waits when\n searching for elements. It can be set by using the `Set Selenium Implicit\n Wait` keyword or with the ``implicit_wait`` argument when `importing`\n the library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp|\n Selenium documentation] for more information about this functionality.\n\n See `time format` below for supported syntax.\n\n == Page load ==\n Page load timeout is the amount of time to wait for page load to complete\n until a timeout exception is raised.\n\n The default page load timeout can be set globally\n when `importing` the library with the ``page_load_timeout`` argument\n or by using the `Set Selenium Page Load Timeout` keyword.\n\n See `time format` below for supported timeout syntax.\n\n Support for page load is new in SeleniumLibrary 6.1\n\n == Selenium speed ==\n\n Selenium execution speed can be slowed down globally by using `Set\n Selenium speed` keyword. This functionality is designed to be used for\n demonstrating or debugging purposes. Using it to make sure that elements\n appear on a page is not a good idea. The above-explained timeouts\n and waits should be used instead.\n\n See `time format` below for supported syntax.\n\n == Time format ==\n\n All timeouts and waits can be given as numbers considered seconds\n (e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax\n (e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about\n the time syntax see the\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide].\n\n = Run-on-failure functionality =\n\n SeleniumLibrary has a handy feature that it can automatically execute\n a keyword if any of its own keywords fails. By default, it uses the\n `Capture Page Screenshot` keyword, but this can be changed either by\n using the `Register Keyword To Run On Failure` keyword or with the\n ``run_on_failure`` argument when `importing` the library. It is\n possible to use any keyword from any imported library or resource file.\n\n The run-on-failure functionality can be disabled by using a special value\n ``NOTHING`` or anything considered false (see `Boolean arguments`)\n such as ``NONE``.\n\n = Boolean arguments =\n\n Starting from 5.0 SeleniumLibrary relies on Robot Framework to perform the\n boolean conversion based on keyword arguments [https://docs.python.org/3/library/typing.html|type hint].\n More details in Robot Framework\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#supported-conversions|user guide]\n\n Please note SeleniumLibrary 3 and 4 did have own custom methods to covert\n arguments to boolean values.\n\n = EventFiringWebDriver =\n\n The SeleniumLibrary offers support for\n [https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver].\n See the Selenium and SeleniumLibrary\n [https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#EventFiringWebDriver|EventFiringWebDriver support]\n documentation for further details.\n\n EventFiringWebDriver is new in SeleniumLibrary 4.0\n\n = Thread support =\n\n SeleniumLibrary is not thread-safe. This is mainly due because the underlying\n [https://github.com/SeleniumHQ/selenium/wiki/Frequently-Asked-Questions#q-is-webdriver-thread-safe|\n Selenium tool is not thread-safe] within one browser/driver instance.\n Because of the limitation in the Selenium side, the keywords or the\n API provided by the SeleniumLibrary is not thread-safe.\n\n = Plugins =\n\n SeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal\n functionality without creating a new library or hacking the source code. See\n [https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#Plugins|plugin API]\n documentation for further details.\n\n Plugin API is new SeleniumLibrary 4.0\n\n = Language =\n\n SeleniumLibrary offers the possibility to translate keyword names and documentation to new language. If language\n is defined, SeleniumLibrary will search from\n [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path | module search path]\n for Python packages starting with `robotframework-seleniumlibrary-translation` by using the\n [https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/ | Python pluging API]. The Library\n is using naming convention to find Python plugins.\n\n The package must implement a single API call, ``get_language`` without any arguments. The method must return a\n dictionary containing two keys: ``language`` and ``path``. The language key value defines which language\n the package contains. Also the value should match (case insensitive) the library ``language`` import parameter.\n The path parameter value should be full path to the translation file.\n\n == Translation file ==\n\n The file name or extension is not important, but data must be in [https://www.json.org/json-en.html | json]\n format. The keys of json are the methods names, not the keyword names, which implements keywords. Value of\n key is json object which contains two keys: ``name`` and ``doc``. The ``name`` key contains the keyword\n translated name and `doc` contains translated documentation. Providing doc and name are optional, example\n translation json file can only provide translations to keyword names or only to documentation. But it is\n always recommended to provide translation to both name and doc. Special key ``__intro__`` is for class level\n documentation and ``__init__`` is for init level documentation. These special values ``name`` can not be\n translated, instead ``name`` should be kept the same.\n\n == Generating template translation file ==\n\n Template translation file, with English language can be created by running:\n `rfselib translation /path/to/translation.json` command. Command does not provide translations to other\n languages, it only provides easy way to create full list keywords and their documentation in correct\n format. It is also possible to add keywords from library plugins by providing `--plugins` arguments\n to command. Example: `rfselib translation --plugins myplugin.SomePlugin /path/to/translation.json` The\n generated json file contains `sha256` key, which contains the sha256 sum of the library documentation.\n The sha256 sum is used by `rfselib translation --compare /path/to/translation.json` command, which compares\n the translation to the library and prints outs a table which tells if there are changes needed for\n the translation file.\n\n Example project for translation can be found from\n [https://github.com/MarketSquare/robotframework-seleniumlibrary-translation-fi | robotframework-seleniumlibrary-translation-fi]\n repository.\n ", - "sha256": "1f433be14145c7db77afbfb62ab2fa90e8ff9bbae428dc5a7d78424f652bad4d" + "doc": "SeleniumLibrary is a web testing library for Robot Framework.\n\n This document explains how to use keywords provided by SeleniumLibrary.\n For information about installation, support, and more, please visit the\n [https://github.com/robotframework/SeleniumLibrary|project pages].\n For more information about Robot Framework, see http://robotframework.org.\n\n SeleniumLibrary uses the Selenium WebDriver modules internally to\n control a web browser. See http://seleniumhq.org for more information\n about Selenium in general and SeleniumLibrary README.rst\n [https://github.com/robotframework/SeleniumLibrary#browser-drivers|Browser drivers chapter]\n for more details about WebDriver binary installation.\n\n %TOC%\n\n = Locating elements =\n\n All keywords in SeleniumLibrary that need to interact with an element\n on a web page take an argument typically named ``locator`` that specifies\n how to find the element. Most often the locator is given as a string\n using the locator syntax described below, but `using WebElements` is\n possible too.\n\n == Locator syntax ==\n\n SeleniumLibrary supports finding elements based on different strategies\n such as the element id, XPath expressions, or CSS selectors. The strategy\n can either be explicitly specified with a prefix or the strategy can be\n implicit.\n\n === Default locator strategy ===\n\n By default, locators are considered to use the keyword specific default\n locator strategy. All keywords support finding elements based on ``id``\n and ``name`` attributes, but some keywords support additional attributes\n or other values that make sense in their context. For example, `Click\n Link` supports the ``href`` attribute and the link text and addition\n to the normal ``id`` and ``name``.\n\n Examples:\n\n | `Click Element` | example | # Match based on ``id`` or ``name``. |\n | `Click Link` | example | # Match also based on link text and ``href``. |\n | `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. |\n\n If a locator accidentally starts with a prefix recognized as `explicit\n locator strategy` or `implicit XPath strategy`, it is possible to use\n the explicit ``default`` prefix to enable the default strategy.\n\n Examples:\n\n | `Click Element` | name:foo | # Find element with name ``foo``. |\n | `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. |\n | `Click Element` | //foo | # Find element using XPath ``//foo``. |\n | `Click Element` | default: //foo | # Use default strategy with value ``//foo``. |\n\n === Explicit locator strategy ===\n\n The explicit locator strategy is specified with a prefix using either\n syntax ``strategy:value`` or ``strategy=value``. The former syntax\n is preferred because the latter is identical to Robot Framework's\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax|\n named argument syntax] and that can cause problems. Spaces around\n the separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo``\n are all equivalent.\n\n Locator strategies that are supported by default are listed in the table\n below. In addition to them, it is possible to register `custom locators`.\n\n | = Strategy = | = Match based on = | = Example = |\n | id | Element ``id``. | ``id:example`` |\n | name | ``name`` attribute. | ``name:example`` |\n | identifier | Either ``id`` or ``name``. | ``identifier:example`` |\n | class | Element ``class``. | ``class:example`` |\n | tag | Tag name. | ``tag:div`` |\n | xpath | XPath expression. | ``xpath://div[@id=\"example\"]`` |\n | css | CSS selector. | ``css:div#example`` |\n | dom | DOM expression. | ``dom:document.images[5]`` |\n | link | Exact text a link has. | ``link:The example`` |\n | partial link | Partial link text. | ``partial link:he ex`` |\n | sizzle | Sizzle selector deprecated. | ``sizzle:div.example`` |\n | data | Element ``data-*`` attribute | ``data:id:my_id`` |\n | jquery | jQuery expression. | ``jquery:div.example`` |\n | default | Keyword specific default behavior. | ``default:example`` |\n\n See the `Default locator strategy` section below for more information\n about how the default strategy works. Using the explicit ``default``\n prefix is only necessary if the locator value itself accidentally\n matches some of the explicit strategies.\n\n Different locator strategies have different pros and cons. Using ids,\n either explicitly like ``id:foo`` or by using the `default locator\n strategy` simply like ``foo``, is recommended when possible, because\n the syntax is simple and locating elements by id is fast for browsers.\n If an element does not have an id or the id is not stable, other\n solutions need to be used. If an element has a unique tag name or class,\n using ``tag``, ``class`` or ``css`` strategy like ``tag:h1``,\n ``class:example`` or ``css:h1.example`` is often an easy solution. In\n more complex cases using XPath expressions is typically the best\n approach. They are very powerful but a downside is that they can also\n get complex.\n\n Examples:\n\n | `Click Element` | id:foo | # Element with id 'foo'. |\n | `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. |\n | `Click Element` | xpath: //div[@id=\"foo\"]//h1 | # Same as the above using XPath, not CSS. |\n | `Click Element` | xpath: //*[contains(text(), \"example\")] | # Element containing text 'example'. |\n\n *NOTE:*\n\n - The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0\n and newer.\n - Using the ``sizzle`` strategy or its alias ``jquery`` requires that\n the system under test contains the jQuery library.\n - Prior to SeleniumLibrary 3.0, table related keywords only supported\n ``xpath``, ``css`` and ``sizzle/jquery`` strategies.\n - ``data`` strategy is conveniance locator that will construct xpath from the parameters.\n If you have element like `
`, you locate the element via\n ``data:automation:automation-id-2``. This feature was added in SeleniumLibrary 5.2.0\n\n === Implicit XPath strategy ===\n\n If the locator starts with ``//`` or multiple opening parenthesis in front\n of the ``//``, the locator is considered to be an XPath expression. In other\n words, using ``//div`` is equivalent to using explicit ``xpath://div`` and\n ``((//div))`` is equivalent to using explicit ``xpath:((//div))``\n\n Examples:\n\n | `Click Element` | //div[@id=\"foo\"]//h1 |\n | `Click Element` | (//div)[2] |\n\n The support for the ``(//`` prefix is new in SeleniumLibrary 3.0.\n Supporting multiple opening parenthesis is new in SeleniumLibrary 5.0.\n\n === Chaining locators ===\n\n It is possible chain multiple locators together as single locator. Each chained locator must start with locator\n strategy. Chained locators must be separated with single space, two greater than characters and followed with\n space. It is also possible mix different locator strategies, example css or xpath. Also a list can also be\n used to specify multiple locators. This is useful, is some part of locator would match as the locator separator\n but it should not. Or if there is need to existing WebElement as locator.\n\n Although all locators support chaining, some locator strategies do not abey the chaining. This is because\n some locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context\n and not for the element found be the previous locator. Chaining is supported by locator strategies which\n are based on Selenium API, like `xpath` or `css`, but example chaining is not supported by `sizzle` or `jquery\n\n Examples:\n | `Click Element` | css:.bar >> xpath://a | # To find a link which is present after an element with class \"bar\" |\n\n List examples:\n | ${locator_list} = | `Create List` | css:div#div_id | xpath://*[text(), \" >> \"] |\n | `Page Should Contain Element` | ${locator_list} | | |\n | ${element} = | Get WebElement | xpath://*[text(), \" >> \"] | |\n | ${locator_list} = | `Create List` | css:div#div_id | ${element} |\n | `Page Should Contain Element` | ${locator_list} | | |\n\n Chaining locators in new in SeleniumLibrary 5.0\n\n == Using WebElements ==\n\n In addition to specifying a locator as a string, it is possible to use\n Selenium's WebElement objects. This requires first getting a WebElement,\n for example, by using the `Get WebElement` keyword.\n\n | ${elem} = | `Get WebElement` | id:example |\n | `Click Element` | ${elem} | |\n\n == Custom locators ==\n\n If more complex lookups are required than what is provided through the\n default locators, custom lookup strategies can be created. Using custom\n locators is a two part process. First, create a keyword that returns\n a WebElement that should be acted on:\n\n | Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} |\n | | ${element}= | Execute Javascript | return window.document.getElementById('${locator}'); |\n | | RETURN | ${element} |\n\n This keyword is a reimplementation of the basic functionality of the\n ``id`` locator where ``${browser}`` is a reference to a WebDriver\n instance and ``${locator}`` is the name of the locator strategy. To use\n this locator, it must first be registered by using the\n `Add Location Strategy` keyword:\n\n | `Add Location Strategy` | custom | Custom Locator Strategy |\n\n The first argument of `Add Location Strategy` specifies the name of\n the strategy and it must be unique. After registering the strategy,\n the usage is the same as with other locators:\n\n | `Click Element` | custom:example |\n\n See the `Add Location Strategy` keyword for more details.\n\n = Browser and Window =\n\n There is different conceptual meaning when SeleniumLibrary talks\n about windows or browsers. This chapter explains those differences.\n\n == Browser ==\n\n When `Open Browser` or `Create WebDriver` keyword is called, it\n will create a new Selenium WebDriver instance by using the\n [https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver]\n API. In SeleniumLibrary terms, a new browser is created. It is\n possible to start multiple independent browsers (Selenium Webdriver\n instances) at the same time, by calling `Open Browser` or\n `Create WebDriver` multiple times. These browsers are usually\n independent of each other and do not share data like cookies,\n sessions or profiles. Typically when the browser starts, it\n creates a single window which is shown to the user.\n\n == Window ==\n\n Windows are the part of a browser that loads the web site and presents\n it to the user. All content of the site is the content of the window.\n Windows are children of a browser. In SeleniumLibrary browser is a\n synonym for WebDriver instance. One browser may have multiple\n windows. Windows can appear as tabs, as separate windows or pop-ups with\n different position and size. Windows belonging to the same browser\n typically share the sessions detail, like cookies. If there is a\n need to separate sessions detail, example login with two different\n users, two browsers (Selenium WebDriver instances) must be created.\n New windows can be opened example by the application under test or\n by example `Execute Javascript` keyword:\n\n | `Execute Javascript` window.open() # Opens a new window with location about:blank\n\n The example below opens multiple browsers and windows,\n to demonstrate how the different keywords can be used to interact\n with browsers, and windows attached to these browsers.\n\n Structure:\n | BrowserA\n | Window 1 (location=https://robotframework.org/)\n | Window 2 (location=https://robocon.io/)\n | Window 3 (location=https://github.com/robotframework/)\n |\n | BrowserB\n | Window 1 (location=https://github.com/)\n\n Example:\n | `Open Browser` | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. |\n | `Execute Javascript` | window.open() | | | # In BrowserA second window is opened. |\n | `Switch Window` | locator=NEW | | | # Switched to second window in BrowserA |\n | `Go To` | https://robocon.io | | | # Second window navigates to robocon site. |\n | `Execute Javascript` | window.open() | | | # In BrowserA third window is opened. |\n | ${handle} | `Switch Window` | locator=NEW | | # Switched to third window in BrowserA |\n | `Go To` | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. |\n | `Open Browser` | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. |\n | ${location} | `Get Location` | | | # ${location} is: https://www.github.com |\n | `Switch Window` | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. |\n | ${location} | `Get Location` | | | # ${location} = https://robocon.io/ |\n | @{locations 1} | `Get Locations` | | | # By default, lists locations under the currectly active browser (BrowserA). |\n | @{locations 2} | `Get Locations` | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. |\n\n The above example, @{locations 1} contains the following items:\n https://robotframework.org/, https://robocon.io/ and\n https://github.com/robotframework/'. The @{locations 2}\n contains the following items: https://robotframework.org/,\n https://robocon.io/, https://github.com/robotframework/'\n and 'https://github.com/.\n\n = Browser and Driver options and service class =\n\n This section talks about how to configure either the browser or\n the driver using the options and service arguments of the `Open\n Browser` keyword.\n\n == Configuring the browser using the Selenium Options ==\n\n As noted within the keyword documentation for `Open Browser`, its\n ``options`` argument accepts Selenium options in two different\n formats: as a string and as Python object which is an instance of\n the Selenium options class.\n\n === Options string format ===\n\n The string format allows defining Selenium options methods\n or attributes and their arguments in Robot Framework test data.\n The method and attributes names are case and space sensitive and\n must match to the Selenium options methods and attributes names.\n When defining a method, it must be defined in a similar way as in\n python: method name, opening parenthesis, zero to many arguments\n and closing parenthesis. If there is a need to define multiple\n arguments for a single method, arguments must be separated with\n comma, just like in Python. Example: `add_argument(\"--headless\")`\n or `add_experimental_option(\"key\", \"value\")`. Attributes are\n defined in a similar way as in Python: attribute name, equal sign,\n and attribute value. Example, `headless=True`. Multiple methods\n and attributes must be separated by a semicolon. Example:\n `add_argument(\"--headless\");add_argument(\"--start-maximized\")`.\n\n Arguments allow defining Python data types and arguments are\n evaluated by using Python\n [https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval].\n Strings must be quoted with single or double quotes, example \"value\"\n or 'value'. It is also possible to define other Python builtin\n data types, example `True` or `None`, by not using quotes\n around the arguments.\n\n The string format is space friendly. Usually, spaces do not alter\n the defining methods or attributes. There are two exceptions.\n In some Robot Framework test data formats, two or more spaces are\n considered as cell separator and instead of defining a single\n argument, two or more arguments may be defined. Spaces in string\n arguments are not removed and are left as is. Example\n `add_argument ( \"--headless\" )` is same as\n `add_argument(\"--headless\")`. But `add_argument(\" --headless \")` is\n not same same as `add_argument ( \"--headless\" )`, because\n spaces inside of quotes are not removed. Please note that if\n options string contains backslash, example a Windows OS path,\n the backslash needs escaping both in Robot Framework data and\n in Python side. This means single backslash must be writen using\n four backslash characters. Example, Windows path:\n \"C:\\path\\to\\profile\" must be written as\n \"C:\\\\\\\\path\\\\\\to\\\\\\\\profile\". Another way to write\n backslash is use Python\n [https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings]\n and example write: r\"C:\\\\path\\\\to\\\\profile\".\n\n === Selenium Options as Python class ===\n\n As last format, ``options`` argument also supports receiving\n the Selenium options as Python class instance. In this case, the\n instance is used as-is and the SeleniumLibrary will not convert\n the instance to other formats.\n For example, if the following code return value is saved to\n `${options}` variable in the Robot Framework data:\n | options = webdriver.ChromeOptions()\n | options.add_argument('--disable-dev-shm-usage')\n | return options\n\n Then the `${options}` variable can be used as an argument to\n ``options``.\n\n Example the ``options`` argument can be used to launch Chomium-based\n applications which utilize the\n [https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework]\n . To launch Chromium-based application, use ``options`` to define\n `binary_location` attribute and use `add_argument` method to define\n `remote-debugging-port` port for the application. Once the browser\n is opened, the test can interact with the embedded web-content of\n the system under test.\n\n == Configuring the driver using the Service class ==\n\n With the ``service`` argument, one can setup and configure the driver. For example\n one can set the driver location and/port or specify the command line arguments. There\n are several browser specific attributes related to logging as well. For the various\n Service Class attributes refer to\n [https://www.selenium.dev/documentation/webdriver/drivers/service/|the Selenium documentation]\n . Currently the ``service`` argument only accepts Selenium service in the string format.\n\n === Service string format ===\n\n The string format allows for defining Selenium service attributes\n and their values in the `Open Browser` keyword. The attributes names\n are case and space sensitive and must match to the Selenium attributes\n names. Attributes are defined in a similar way as in Python: attribute\n name, equal sign, and attribute value. Example, `port=1234`. Multiple\n attributes must be separated by a semicolon. Example:\n `executable_path='/path/to/driver';port=1234`. Don't have duplicate\n attributes, like `service_args=['--append-log', '--readable-timestamp'];\n service_args=['--log-level=DEBUG']` as the second will override the first.\n Instead combine them as in\n `service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']`\n\n Arguments allow defining Python data types and arguments are\n evaluated by using Python. Strings must be quoted with single\n or double quotes, example \"value\" or 'value'\n\n = Timeouts, waits, and delays =\n\n This section discusses different ways how to wait for elements to\n appear on web pages and to slow down execution speed otherwise.\n It also explains the `time format` that can be used when setting various\n timeouts, waits, and delays.\n\n == Timeout ==\n\n SeleniumLibrary contains various keywords that have an optional\n ``timeout`` argument that specifies how long these keywords should\n wait for certain events or actions. These keywords include, for example,\n ``Wait ...`` keywords and keywords related to alerts. Additionally\n `Execute Async Javascript`. Although it does not have ``timeout``,\n argument, uses a timeout to define how long asynchronous JavaScript\n can run.\n\n The default timeout these keywords use can be set globally either by\n using the `Set Selenium Timeout` keyword or with the ``timeout`` argument\n when `importing` the library. If no default timeout is set globally, the\n default is 5 seconds. If None is specified for the timeout argument in the\n keywords, the default is used. See `time format` below for supported\n timeout syntax.\n\n == Implicit wait ==\n\n Implicit wait specifies the maximum time how long Selenium waits when\n searching for elements. It can be set by using the `Set Selenium Implicit\n Wait` keyword or with the ``implicit_wait`` argument when `importing`\n the library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp|\n Selenium documentation] for more information about this functionality.\n\n See `time format` below for supported syntax.\n\n == Page load ==\n Page load timeout is the amount of time to wait for page load to complete\n until a timeout exception is raised.\n\n The default page load timeout can be set globally\n when `importing` the library with the ``page_load_timeout`` argument\n or by using the `Set Selenium Page Load Timeout` keyword.\n\n See `time format` below for supported timeout syntax.\n\n Support for page load is new in SeleniumLibrary 6.1\n\n == Selenium speed ==\n\n Selenium execution speed can be slowed down globally by using `Set\n Selenium speed` keyword. This functionality is designed to be used for\n demonstrating or debugging purposes. Using it to make sure that elements\n appear on a page is not a good idea. The above-explained timeouts\n and waits should be used instead.\n\n See `time format` below for supported syntax.\n\n == Time format ==\n\n All timeouts and waits can be given as numbers considered seconds\n (e.g. ``0.5`` or ``42``) or in Robot Framework's time syntax\n (e.g. ``1.5 seconds`` or ``1 min 30 s``). For more information about\n the time syntax see the\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide].\n\n = Run-on-failure functionality =\n\n SeleniumLibrary has a handy feature that it can automatically execute\n a keyword if any of its own keywords fails. By default, it uses the\n `Capture Page Screenshot` keyword, but this can be changed either by\n using the `Register Keyword To Run On Failure` keyword or with the\n ``run_on_failure`` argument when `importing` the library. It is\n possible to use any keyword from any imported library or resource file.\n\n The run-on-failure functionality can be disabled by using a special value\n ``NOTHING`` or anything considered false (see `Boolean arguments`)\n such as ``NONE``.\n\n = Boolean arguments =\n\n Starting from 5.0 SeleniumLibrary relies on Robot Framework to perform the\n boolean conversion based on keyword arguments [https://docs.python.org/3/library/typing.html|type hint].\n More details in Robot Framework\n [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#supported-conversions|user guide]\n\n Please note SeleniumLibrary 3 and 4 did have own custom methods to covert\n arguments to boolean values.\n\n = EventFiringWebDriver =\n\n The SeleniumLibrary offers support for\n [https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver].\n See the Selenium and SeleniumLibrary\n [https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#EventFiringWebDriver|EventFiringWebDriver support]\n documentation for further details.\n\n EventFiringWebDriver is new in SeleniumLibrary 4.0\n\n = Thread support =\n\n SeleniumLibrary is not thread-safe. This is mainly due because the underlying\n [https://github.com/SeleniumHQ/selenium/wiki/Frequently-Asked-Questions#q-is-webdriver-thread-safe|\n Selenium tool is not thread-safe] within one browser/driver instance.\n Because of the limitation in the Selenium side, the keywords or the\n API provided by the SeleniumLibrary is not thread-safe.\n\n = Plugins =\n\n SeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal\n functionality without creating a new library or hacking the source code. See\n [https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#Plugins|plugin API]\n documentation for further details.\n\n Plugin API is new SeleniumLibrary 4.0\n\n = Language =\n\n SeleniumLibrary offers the possibility to translate keyword names and documentation to new language. If language\n is defined, SeleniumLibrary will search from\n [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path | module search path]\n for Python packages starting with `robotframework-seleniumlibrary-translation` by using the\n [https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/ | Python pluging API]. The Library\n is using naming convention to find Python plugins.\n\n The package must implement a single API call, ``get_language`` without any arguments. The method must return a\n dictionary containing two keys: ``language`` and ``path``. The language key value defines which language\n the package contains. Also the value should match (case insensitive) the library ``language`` import parameter.\n The path parameter value should be full path to the translation file.\n\n == Translation file ==\n\n The file name or extension is not important, but data must be in [https://www.json.org/json-en.html | json]\n format. The keys of json are the methods names, not the keyword names, which implements keywords. Value of\n key is json object which contains two keys: ``name`` and ``doc``. The ``name`` key contains the keyword\n translated name and `doc` contains translated documentation. Providing doc and name are optional, example\n translation json file can only provide translations to keyword names or only to documentation. But it is\n always recommended to provide translation to both name and doc. Special key ``__intro__`` is for class level\n documentation and ``__init__`` is for init level documentation. These special values ``name`` can not be\n translated, instead ``name`` should be kept the same.\n\n == Generating template translation file ==\n\n Template translation file, with English language can be created by running:\n `rfselib translation /path/to/translation.json` command. Command does not provide translations to other\n languages, it only provides easy way to create full list keywords and their documentation in correct\n format. It is also possible to add keywords from library plugins by providing `--plugins` arguments\n to command. Example: `rfselib translation --plugins myplugin.SomePlugin /path/to/translation.json` The\n generated json file contains `sha256` key, which contains the sha256 sum of the library documentation.\n The sha256 sum is used by `rfselib translation --compare /path/to/translation.json` command, which compares\n the translation to the library and prints outs a table which tells if there are changes needed for\n the translation file.\n\n Example project for translation can be found from\n [https://github.com/MarketSquare/robotframework-seleniumlibrary-translation-fi | robotframework-seleniumlibrary-translation-fi]\n repository.\n ", + "sha256": "af42a24b1bda192c4beb4feef802fc8938cddd81554670e1627895c5ad1ed5c6" } } \ No newline at end of file