Red Alert 2 Shortcut Keys

[Mellissa Sprock]

Thisdocument explains how to use keywords provided by SeleniumLibrary. For information about installation, support, and more, please visit the project pages. For more information about Robot Framework, see

SeleniumLibrary uses the Selenium WebDriver modules internally to control a web browser. See for more information about Selenium in general and SeleniumLibrary README.rst Browser drivers chapter for more details about WebDriver binary installation.

All keywords in SeleniumLibrary that need to interact with an element on a web page take an argument typically named locator that specifies how to find the element. Most often the locator is given as a string using the locator syntax described below, but using WebElements is possible too.

SeleniumLibrary supports finding elements based on different strategies such as the element id, XPath expressions, or CSS selectors. The strategy can either be explicitly specified with a prefix or the strategy can be implicit.

By default, locators are considered to use the keyword specific default locator strategy. All keywords support finding elements based on id and name attributes, but some keywords support additional attributes or other values that make sense in their context. For example, Click Link supports the href attribute and the link text and addition to the normal id and name.

The explicit locator strategy is specified with a prefix using either syntax strategy:value or strategy=value. The former syntax is preferred because the latter is identical to Robot Framework's named argument syntax and that can cause problems. Spaces around the separator are ignored, so id:foo, id: foo and id : foo are all equivalent.

See the Default locator strategy section below for more information about how the default strategy works. Using the explicit default prefix is only necessary if the locator value itself accidentally matches some of the explicit strategies.

Different locator strategies have different pros and cons. Using ids, either explicitly like id:foo or by using the default locator strategy simply like foo, is recommended when possible, because the syntax is simple and locating elements by id is fast for browsers. If an element does not have an id or the id is not stable, other solutions need to be used. If an element has a unique tag name or class, using tag, class or css strategy like tag:h1, class:example or css:h1.example is often an easy solution. In more complex cases using XPath expressions is typically the best approach. They are very powerful but a downside is that they can also get complex.

It is possible chain multiple locators together as single locator. Each chained locator must start with locator strategy. Chained locators must be separated with single space, two greater than characters and followed with space. It is also possible mix different locator strategies, example css or xpath. Also a list can also be used to specify multiple locators. This is useful, is some part of locator would match as the locator separator but it should not. Or if there is need to existing WebElement as locator.

Although all locators support chaining, some locator strategies do not abey the chaining. This is because some locator strategies use JavaScript to find elements and JavaScript is executed for the whole browser context and not for the element found be the previous locator. Chaining is supported by locator strategies which are based on Selenium API, like xpath or css, but example chaining is not supported by sizzle or `jquery

If more complex lookups are required than what is provided through the default locators, custom lookup strategies can be created. Using custom locators is a two part process. First, create a keyword that returns a WebElement that should be acted on:

This keyword is a reimplementation of the basic functionality of the id locator where $browser is a reference to a WebDriver instance and $locator is the name of the locator strategy. To use this locator, it must first be registered by using the Add Location Strategy keyword:

When Open Browser or Create WebDriver keyword is called, it will create a new Selenium WebDriver instance by using the Selenium WebDriver API. In SeleniumLibrary terms, a new browser is created. It is possible to start multiple independent browsers (Selenium Webdriver instances) at the same time, by calling Open Browser or Create WebDriver multiple times. These browsers are usually independent of each other and do not share data like cookies, sessions or profiles. Typically when the browser starts, it creates a single window which is shown to the user.

Windows are the part of a browser that loads the web site and presents it to the user. All content of the site is the content of the window. Windows are children of a browser. In SeleniumLibrary browser is a synonym for WebDriver instance. One browser may have multiple windows. Windows can appear as tabs, as separate windows or pop-ups with different position and size. Windows belonging to the same browser typically share the sessions detail, like cookies. If there is a need to separate sessions detail, example login with two different users, two browsers (Selenium WebDriver instances) must be created. New windows can be opened example by the application under test or by example Execute Javascript keyword:

As noted within the keyword documentation for Open Browser, its options argument accepts Selenium options in two different formats: as a string and as Python object which is an instance of the Selenium options class.

The string format allows defining Selenium options methods or attributes and their arguments in Robot Framework test data. The method and attributes names are case and space sensitive and must match to the Selenium options methods and attributes names. When defining a method, it must be defined in a similar way as in python: method name, opening parenthesis, zero to many arguments and closing parenthesis. If there is a need to define multiple arguments for a single method, arguments must be separated with comma, just like in Python. Example: add_argument(\"--headless\") or add_experimental_option(\"key\", \"value\"). Attributes are defined in a similar way as in Python: attribute name, equal sign, and attribute value. Example, headless=True. Multiple methods and attributes must be separated by a semicolon. Example: add_argument(\"--headless\");add_argument(\"--start-maximized\").

Arguments allow defining Python data types and arguments are evaluated by using Python ast.literal_eval. Strings must be quoted with single or double quotes, example \"value\" or 'value'. It is also possible to define other Python builtin data types, example True or None, by not using quotes around the arguments.

The string format is space friendly. Usually, spaces do not alter the defining methods or attributes. There are two exceptions. In some Robot Framework test data formats, two or more spaces are considered as cell separator and instead of defining a single argument, two or more arguments may be defined. Spaces in string arguments are not removed and are left as is. Example add_argument ( \"--headless\" ) is same as add_argument(\"--headless\"). But add_argument(\" --headless \") is not same same as add_argument ( \"--headless\" ), because spaces inside of quotes are not removed. Please note that if options string contains backslash, example a Windows OS path, the backslash needs escaping both in Robot Framework data and in Python side. This means single backslash must be writen using four backslash characters. Example, Windows path: \"C:\\path\\to\\profile\" must be written as \"C:\\\\\\\\path\\\\\\to\\\\\\\\profile\". Another way to write backslash is use Python raw strings and example write: r\"C:\\\\path\\\\to\\\\profile\".

As last format, options argument also supports receiving the Selenium options as Python class instance. In this case, the instance is used as-is and the SeleniumLibrary will not convert the instance to other formats. For example, if the following code return value is saved to $options variable in the Robot Framework data:

Example the options argument can be used to launch Chomium-based applications which utilize the Chromium Embedded Framework . To launch Chromium-based application, use options to define binary_location attribute and use add_argument method to define remote-debugging-port port for the application. Once the browser is opened, the test can interact with the embedded web-content of the system under test.

With the service argument, one can setup and configure the driver. For example one can set the driver location and/port or specify the command line arguments. There are several browser specific attributes related to logging as well. For the various Service Class attributes refer to the Selenium documentation . Currently the service argument only accepts Selenium service in the string format.

The string format allows for defining Selenium service attributes and their values in the Open Browser keyword. The attributes names are case and space sensitive and must match to the Selenium attributes names. Attributes are defined in a similar way as in Python: attribute name, equal sign, and attribute value. Example, port=1234. Multiple attributes must be separated by a semicolon. Example: executable_path='/path/to/driver';port=1234. Don't have duplicate attributes, like service_args=['--append-log', '--readable-timestamp']; service_args=['--log-level=DEBUG'] as the second will override the first. Instead combine them as in service_args=['--append-log', '--readable-timestamp', '--log-level=DEBUG']

This section discusses different ways how to wait for elements to appear on web pages and to slow down execution speed otherwise. It also explains the time format that can be used when setting various timeouts, waits, and delays.

SeleniumLibrary contains various keywords that have an optional timeout argument that specifies how long these keywords should wait for certain events or actions. These keywords include, for example, Wait ... keywords and keywords related to alerts. Additionally Execute Async Javascript. Although it does not have timeout, argument, uses a timeout to define how long asynchronous JavaScript can run.

3a8082e126