-
-
- More browser supported -
-
-
-
-
- ipad -
- safari -
-
- - Custom JavaScript Locators -
- We added the keyword Add Location Strategy. This keyword is somewhat
-analogous to the SeleniumLibrary (RC) keyword. It can be used to register
-a JavaScript function as locator with the specified strategy name. The
-registered function has to return a WebElement, a List of WebElements or
-null. This feature was requested in issue #1.
-
-Since 1.2.0.1 an optional delimiter can be specified. See #3 for more info.
-
-
-Keyword Arguments Add Location Strategy strategy_name, function_definition, delimiter=NONE
-
-
-
- Proxy Handling -
- We added proper proxy handling for RemoteWebDriver instances. This is
-needed, if you want to connect to an external Selenium grid through a
-local HTTP proxy. Our implementation handles BASIC, DIGEST and NTLM
-based authentication schemes correctly. We added the following keyword.
-
-
-Some additional info: -Keyword Arguments Set Remote Web Driver Proxy host,port,user=NONE,password=NONE,domain=NONE,workstation=NONE -
-
- If you set a proxy, it will be used for all subsequent calls of Open Browser -
- You can remove the proxy by calling: Set Remote Web Driver Proxy ${EMPTY} ${EMPTY} -
- If you provide no username, we are looking for a username at the Java property http.proxyUser and the environment variables HTTP_PROXY and http_proxy. If we find a username, it is only used, if the host and port also match. -
- If you provide no password, we are looking for a password at the Java property http.proxyUser and the environment variables HTTP_PROXY and http_proxy. If we find a password, it is only used, if the host, port and username also match. -
- If you provide a domain, we use NTLM based authentication -
- If you provide no workstation and we use NTLM based authentication, we use the hostname as workstation name -
-
- - Waiting -
- Our application is heavily using AJAX. So much more waiting keywords
-are needed. The list of new keywords:
-
-
-Keyword Arguments Element Should Be Clickable locator,message=NONE Element Should Not Be Clickable locator,message=NONE Element Should Be Selected locator,message=NONE Element Should Not Be Selected locator,message=NONE Element Should Not Contain locator,expected,message=NONE Element Should Text Should Not Be locator,expected,message=NONE Wait Until Element Is Clickable locator,timeout=NONE,message=NONE Wait Until Element Is Successfully Clicked locator,timeout=NONE,message=NONE Wait Until Element Is Not Clickable locator,timeout=NONE,message=NONE Wait Until Element Is Selected locator,timeout=NONE,message=NONE Wait Until Element Is Not Selected locator,timeout=NONE,message=NONE Wait Until Element Is Not Visible locator,timeout=NONE,message=NONE Wait Until Page Not Contains condition,timeout=NONE,message=NONE Wait Until Page Not Contains Element locator,timeout=NONE,message=NONE Wait Until Title Is title,timeout=NONE,message=NONE Wait Until Title Is Not title,timeout=NONE,message=NONE Wait Until Title Contains title,timeout=NONE,message=NONE Wait Until Title Not Contains title,timeout=NONE,message=NONE
-
- - XPath Count -
- We extended the following keywords to be called with a
-xpath statement that optionally can start with "xpath=".
-
-
-Keyword Arguments Get Matching Xpath Count xpath Xpath Should Match X Times xpath, expected_xpath_count, message=NONE, loglevel=INFO
-
- - Remote Session Id -
- We introduced two keywords to get the session id from the
-RemoteWebDriver. This is mainly needed to identify the test
-session at external grids like SauceLabs.
-
-
-Keyword Arguments Get Remote Session Id Log Remote Session Id
-
- - Remote Capabilities -
- According to the Javadoc no error is thrown, if a session cannot support a capability that is requested
-in the desired capabilities. Therefore it can happen that you are silently running your tests on the wrong
-environment. With the following two keywords you can control what capabilities the actual session supports.
-
-
-Keyword Arguments Get Remote Capabilities Log Remote Capabilities
-
- - System Info -
- The following two keywords are outputting the current system info as in the WebDriverException.
-
-
-Keyword Arguments Get System Info Log System Info
-
+ *
+ * Before running tests
+ * Prior to running test cases using Selenium2Library, the library must be + * imported into your Robot Framework test suite (see importing section), and + * the `Open Browser` keyword must be used to open a browser to the desired + * location.
+ *
+ * Locating elements
+ * All keywords in Selenium2Library that need to find an element on the page + * take an locator argument.
+ *
+ * Key attributes
+ * By default, when a locator value is provided, it is matched against the key + * attributes of the particular element type. The attributes id and + * name are key attributes to all elements.
+ *
+ * List of key attributes: + *
| Element Type | + *Key Attributes | + *
| A | + *@id,@name,@href,text | + *
| IMG | + *@id,@name,@src,@alt | + *
| INPUT | + *@id,@name,@value,@src | + *
| BUTTON | + *@id,@name,@value,text | + *
| * | + *@id,@name | + *
+ * Example: + *
| Click Element | + *my_element | + *
+ * Locator strategies
+ * It is also possible to specify the approach Selenium2Library should take to + * find an element by specifying a locator strategy with a locator prefix.
+ *
+ * Supported strategies are: + *
| Strategy | + *Example | + *Description | + *
| identifier | + *Click Element | identifier=my_element | + *Matches by @id or @name attribute | + *
| id | + *Click Element | id=my_element | + *Matches by @id attribute | + *
| name | + *Click Element | name=my_element | + *Matches by @name attribute | + *
| xpath | + *Click Element | xpath=//div[@id='my_element'] | + *Matches by arbitrary XPath expression | + *
| dom | + *Click Element | dom=document.images[56] | + *Matches by arbitrary DOM expression | + *
| link | + *Click Element | link=My Link | + *Matches by the link text | + *
| css | + *Click Element | css=div.my_class | + *Matches by CSS selector | + *
| jquery | + *Click Element | jquery=div.my_class | + *Matches by jQuery/sizzle selector | + *
| sizzle | + *Click Element | sizzle=div.my_class | + *Matches by jQuery/sizzle selector | + *
| tag | + *Click Element | tag=div | + *Matches by HTML tag name | + *
+ * Locating tables
+ * Table related keywords, such as `Table Should Contain`, work differently. By + * default, when a table locator value is provided, it will search for a table + * with the specified id attribute.
+ *
+ * Example:
+ *
| Table Should Contain | + *my_table | + *text | + *
+ * More complex table locator strategies: + *
| Strategy | + *Example | + *Description | + *xpath | + *Table Should Contain | xpath=//table/[@name="my_table"] | text | + *Matches by arbitrary XPath expression | + * + *css | + *Table Should Contain | css=table.my_class | text | + *Matches by CSS selector | + * + *
+ * Custom location strategies
+ * It is also possible to register custom location strategies. See `Add Location + * Strategy` for details about custom location strategies.
+ *
+ * Example: + *
| Add Location Strategy | + *custom | + *return window.document.getElementById(arguments[0]); | + *
| Input Text | + *custom=firstName | + *Max | + *
+ * Timeouts
+ * There are several Wait ... keywords that take timeout as an argument. + * All of these timeout arguments are optional. The timeout used by all of them + * can be set globally using the `Set Selenium Timeout keyword`.
+ *
+ * All timeouts can be given as numbers considered seconds (e.g. 0.5 or 42) or + * in Robot Framework's time syntax (e.g. '1.5 seconds' or '1 min 30 s'). See Time Format for details about the time syntax.
+ *
+ * Log Level
+ * There are several keywords that take timeout as an argument. All of + * these timeout arguments are optional. The default is usually INFO.
+ *
+ * List of log levels: + *
| Log Level | + *Description | + *
| DEBUG | + *+ * |
| INFO | + *+ * |
| HTML | + *Same as INFO, but message is in HTML format | + *
| TRACE | + *+ * |
| WARN | + *+ * |
+ *
+ * timeout is the default timeout used to wait for all waiting + * actions. It can be changed later with `Set Selenium Timeout`.
+ *
+ * implicitWait is the implicit timeout that Selenium waits, when + * looking for elements. It can be changed later with `Set Selenium Implicit + * Wait`. See WebDriver: Advanced Usage of the SeleniumHQ documentation for + * details about WebDriver's implicit wait functionality.
+ *
+ * runOnFailure specifies the name of a keyword (from any available + * libraries) to execute when a Selenium2Library keyword fails. By default + * `Capture Page Screenshot` will be used to take a screenshot of the + * current page. Using the value \"Nothing\" will disable this feature + * altogether. See `Register Keyword To Run On Failure` keyword for details + * about this functionality.
+ *
+ * Examples: + *
| Library | + *Selenium2Library | + *+ * | + * | + * | + * |
| Library | + *Selenium2Library | + *15 | + *+ * | + * | # Sets timeout to 15 seconds | + *
| Library | + *Selenium2Library | + *0 | + *5 | + *+ * | # Sets timeout to 0 seconds and implicitWait to 5 seconds | + *
| Library | + *Selenium2Library | + *0 | + *5 | + *Log Source | + *# Sets timeout to 0 seconds, implicitWait to 5 seconds and runs `Log + * Source` on failure | + *
| Library | + *Selenium2Library | + *0 | + *5 | + *Nothing | + *# Sets timeout to 0 seconds, implicitWait to 5 seconds and does + * nothing on failure | + *
+ *
+ * The registered function has to return a WebElement, a List of WebElements + * or null. Optionally a delimiter can be given to split the value of the + * locator in multiple arguments when executing the JavaScript function.
+ *
+ * Example: + *
| Add Location Strategy | + *byId | + *return window.document.getElementById(arguments[0]); | + *
| Input Text | + *byId=firstName | + *Max | + *
+ * Example with delimiter: + *
| Add Location Strategy | + *byClassname | + *return + * window.document.getElementsByClassName(arguments[0])[arguments[1]]; | + *, | + *
| Input Text | + *byClassname=input,3 | + *Max | + *+ * |
+ * + * @see BrowserManagement#closeAllBrowsers + * @see BrowserManagement#openBrowser + * @see BrowserManagement#switchBrowser + */ + @RobotKeyword public void closeBrowser() { if (webDriverCache.getCurrentSessionId() != null) { - debug(String.format("Closing browser with session id %s", - webDriverCache.getCurrentSessionId())); + logging.debug(String.format("Closing browser with session id %s", webDriverCache.getCurrentSessionId())); webDriverCache.close(); } } + @RobotKeywordOverload public String openBrowser(String url) throws Throwable { return openBrowser(url, "firefox"); } + @RobotKeywordOverload public String openBrowser(String url, String browserName) throws Throwable { return openBrowser(url, browserName, null); } - public String openBrowser(String url, String browserName, String alias) - throws Throwable { + @RobotKeywordOverload + public String openBrowser(String url, String browserName, String alias) throws Throwable { return openBrowser(url, browserName, alias, null); } - public String openBrowser(String url, String browserName, String alias, - String remoteUrl) throws Throwable { + @RobotKeywordOverload + public String openBrowser(String url, String browserName, String alias, String remoteUrl) throws Throwable { return openBrowser(url, browserName, alias, remoteUrl, null); } - public String openBrowser(String url, String browserName, String alias, - String remoteUrl, String desiredCapabilities) throws Throwable { - return openBrowser(url, browserName, alias, remoteUrl, - desiredCapabilities, null); + public String openBrowser(String url, String browserName, String alias, String remoteUrl, String desiredCapabilities) + throws Throwable { + return openBrowser(url, browserName, alias, remoteUrl, desiredCapabilities, null); } - public String openBrowser(String url, String browserName, String alias, - String remoteUrl, String desiredCapabilities, String ffProfileDir) - throws Throwable { + /** + * Opens a new browser instance to given URL.
+ *
+ * Possible values for browser are as follows: + *
| firefox | + *FireFox | + *
| ff | + *FireFox | + *
| internetexplorer | + *Internet Explorer | + *
| ie | + *Internet Explorer | + *
| googlechrome | + *Google Chrome | + *
| gc | + *Google Chrome | + *
| chrome | + *Google Chrome | + *
| opera | + *Opera | + *
| phantomjs | + *PhantomJS | + *
| htmlunitwithjs | + *HTMLUnit with Javascipt support | + *
| safari | + *Safari | + *
| ipad | + *iPad | + *
| iphone | + *iPhone | + *
| android | + *Android | + *
| htmlunit | + *HTMLUnit | + *
+ * Returns the index of the newly created browser instance which can be used + * later to switch back to it. Index starts from 1 and is reset back to it + * when the `Close All Browsers` keyword is used.
+ *
+ * DesiredCapabilities
+ * The DesiredCapabilities can be specified in a simple key:value format or + * as a JSON object. With the JSON format more complex parameters, like the + * proxy, can be configured.
+ *
+ * Example of desiredCapabilities as simple string:
+ *
| platform:Windows 8,browserName:firefox,version:25 | + *
+ * Example of desiredCapabilities as JSON object:
+ *
|
+ * { + * "platform":"Windows 8", + * "browserName":"firefox", + * "version":"25", + * "proxy": + * { + * "proxyType":"manual", + * "httpProxy":"localhost:8118" + * } + * } + * |
+ *
+ * BrowserOptions
+ * The BrowserOptions can be specified as JSON object to set more complex + * browser specific parameters. At the moment only the following browsers + * with the listed options are implemented.
+ *
+ * Firefox: + *
|
+ * { + * "preferences": + * { + * "extensions.firebug.currentVersion":"1.8.1", + * "extensions.firebug.addonBarOpened":true, + * "extensions.firebug.enableSites":true + * } + * "extensions": + * [ + * "firebug-1.8.1.xpi", + * "modify_headers-0.7.1.1-fx.xpi" + * ] + * } + * |
+ *
+ * Internet Explorer
+ * Note, that you will encounter strange behavior, if you open multiple + * Internet Explorer browser instances. That is also why `Switch Browser` + * only works with one IE browser at most. For more information see: Strange errors with multiple IE instances
+ * + * @param url + * The URL to open in the newly created browser instance. + * @param browserName + * Default=firefox. Optional name of the browser to start. + * @param alias + * Default=NONE. Optional alias for the newly created browser + * instance. The alias can be used later for switching between + * browsers instances, just as returned index. + * @param remoteUrl + * Default=NONE. Optional remote grid URL. When specified no + * local WebDriver instance is created, but a network connection + * to a Selenium 2 WebDriver Grid Hub at the given URL is opened. + * @param desiredCapabilities + * Default=NONE. Optional desired capabilities of the newly + * created remote browser instances can be specified in a simple + * key1:val1,key2:val2 format or as a JSON object (see examples + * above). Used to communicate to the remote grid, which kind of + * browser, etc. should be used. For more information see: DesiredCapabilities + * @return The index of the newly created browser instance. + * + * @see BrowserManagement#closeAllBrowsers + * @see BrowserManagement#closeBrowser + * @see BrowserManagement#switchBrowser + */ + @RobotKeyword + @ArgumentNames({ "url", "browserName=firefox", "alias=NONE", "remoteUrl=NONE", "desiredCapabilities=NONE", + "browserOptions=NONE" }) + public String openBrowser(String url, String browserName, String alias, String remoteUrl, + String desiredCapabilities, String browserOptions) throws Throwable { try { - info("browserName: " + browserName); + logging.info("browserName: " + browserName); if (remoteUrl != null) { - info(String - .format("Opening browser '%s' to base url '%s' through remote server at '%s'", - browserName, url, remoteUrl)); + logging.info(String.format("Opening browser '%s' to base url '%s' through remote server at '%s'", + browserName, url, remoteUrl)); } else { - info(String.format("Opening browser '%s' to base url '%s'", - browserName, url)); + logging.info(String.format("Opening browser '%s' to base url '%s'", browserName, url)); } - WebDriver webDriver = createWebDriver(browserName, - desiredCapabilities, ffProfileDir, remoteUrl); + WebDriver webDriver = createWebDriver(browserName, desiredCapabilities, remoteUrl, browserOptions); webDriver.get(url); String sessionId = webDriverCache.register(webDriver, alias); - debug(String.format("Opened browser with session id %s", sessionId)); + logging.debug(String.format("Opened browser with session id %s", sessionId)); return sessionId; } catch (Throwable t) { if (remoteUrl != null) { - warn(String - .format("Opening browser '%s' to base url '%s' through remote server at '%s' failed", - browserName, url, remoteUrl)); + logging.warn(String.format( + "Opening browser '%s' to base url '%s' through remote server at '%s' failed", browserName, url, + remoteUrl)); } else { - warn(String.format( - "Opening browser '%s' to base url '%s' failed", - browserName, url)); + logging.warn(String.format("Opening browser '%s' to base url '%s' failed", browserName, url)); } throw new Selenium2LibraryFatalException(t); } } + /** + * "Switches between active browser instances using an index or an + * alias.
+ *
+ * The index is returned from `Open Browser` and an alias can be given to + * it.
+ *
+ * Example: + *
| Open Browser | + *http://google.com | + *ff | + *+ * |
| Location Should Be | + *http://google.com | + *+ * | + * |
| Open Browser | + *http://yahoo.com | + *ie | + *2nd conn | + *
| Location Should Be | + *http://yahoo.com | + *+ * | + * |
| Switch Browser | + *1 | + *# index | + *+ * |
| Page Should Contain | + *I'm feeling lucky | + *+ * | + * |
| Switch Browser | + *2nd conn | + *# alias | + *+ * |
| Page Should Contain | + *More Yahoo! | + *+ * | + * |
| Close All Browsers | + *+ * | + * | + * |
+ * The above example expects that there was no other open browsers when + * opening the first one because it used index '1' when switching to it + * later. If you aren't sure about that you can store the index into a + * variable as below. + *
| ${id} = | + *Open Browser | + *http://google.com | + *
| # Do something ... | + *+ * | + * |
| Switch Browser | + *${id} | + *+ * |
+ *
+ * After this keyword new indexes returned from `Open Browser` keyword are + * reset to 1. This keyword should be used in test or suite teardown to make + * sure all browsers are closed.
+ * + * @see BrowserManagement#closeBrowser + * @see BrowserManagement#openBrowser + * @see BrowserManagement#switchBrowser + */ + @RobotKeyword public void closeAllBrowsers() { - debug("Closing all browsers"); + logging.debug("Closing all browsers"); webDriverCache.closeAll(); } + /** + * Closes the currently open pop-up window. + */ + @RobotKeyword public void closeWindow() { webDriverCache.getCurrent().close(); } + /** + * Returns the id attributes of all windows known to the current browser + * instance.
+ * + * @return List of window id attributes + * + * @see Logging#logWindowIdentifiers + */ + @RobotKeyword public List
+ * + * @return List of window names + * + * @see Logging#logWindowNames + */ + @RobotKeyword public List
+ * + * @return List of window titles + * + * @see Logging#logWindowTitles + */ + @RobotKeyword public List
+ */ + @RobotKeyword public void maximizeBrowserWindow() { webDriverCache.getCurrent().manage().window().maximize(); } + /** + * Returns current window size as width then height.
+ *
+ * Example: + *
| ${width} | + *${height}= | + *Get Window Size | + *
+ *
+ * Example: + *
| Set Window Size | + *800 | + *600 | + *
| ${width} | + *${height}= | + *Get Window Size | + *
| Should Be Equal | + *${width} | + *800 | + *
| Should Be Equal | + *${height} | + *600 | + *
+ *
+ * Key attributes for frames are id and name. See + * `Introduction` for details about locators.
+ * + * @param locator + * The locator to locate the frame + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void selectFrame(String locator) { - info(String.format("Selecting frame '%s'.", locator)); - List
+ *
+ * If the window is found, all subsequent commands use that window, until + * this keyword is used again. If the window is not found, this keyword + * fails.
+ *
+ * By default, when a locator value is provided, it is matched against the + * title of the window and the javascript name of the window. If multiple + * windows with same identifier are found, the first one is selected.
+ *
+ * The special locator main (default) can be used to select the main window.
+ *
+ * Example: + *
| Click Link | + *popup_link | + *# opens new window | + *
| Select Window | + *popupName | + *+ * |
| Title Should Be | + *Popup Title | + *+ * |
| Select Window | + *+ * | # Chooses the main window again | + *
+ * It is also possible to specify the approach Selenium2Library should take + * to find a window by specifying a locator strategy. See `Introduction` for + * details about locators: + *
| Strategy | + *Example | + *Description | + *
| title | + *Select Window | title=My Document | + *Matches by window title | + *
| name | + *Select Window | name=${name} | + *Matches by window javascript name | + *
| url | + *Select Window | url=http://google.com | + *Matches by window's current URL | + *
+ *
+ * Not all server implementations will support every WebDriver feature. + * Therefore, the client and server should use JSON objects with the + * properties listed below when describing which features a user requests + * that a session support. If a session cannot support a capability that + * is requested in the desired capabilities, no error is thrown; a + * read-only capabilities object is returned that indicates the capabilities + * the session actually supports. For more information see: DesiredCapabilities
+ * + * @return The capabilities of the remote node. + * + * @see Logging#logRemoteCapabilities + */ + @RobotKeyword + public String getRemoteCapabilities() { + if (getCurrentWebDriver() instanceof RemoteWebDriver) { + return ((RemoteWebDriver) getCurrentWebDriver()).getCapabilities().toString(); + } else { + return "No remote session id"; + } + } + + /** + * Returns the session id of the remote browser instance.
+ * + * @return The remote session id. + * + * @see Logging#logRemoteSessionId + */ + @RobotKeyword + public String getRemoteSessionId() { + if (getCurrentWebDriver() instanceof RemoteWebDriver) { + return ((RemoteWebDriver) getCurrentWebDriver()).getSessionId().toString(); + } else { + return "No remote session id"; + } + } + + /** + * Returns basic system information about the execution environment.
+ * + * @return System information. + * + * @see Logging#logSystemInfo + */ + @RobotKeyword + public String getSystemInfo() { + return String.format(" os.name: '%s'\n os.arch: '%s'\n os.version: '%s'\n java.version: '%s'", + System.getProperty("os.name"), System.getProperty("os.arch"), System.getProperty("os.version"), + System.getProperty("java.version")); + } + + /** + * Verify the current page URL is exactly url.
+ * + * @param url + * The URL to verify. + * + * @see BrowserManagement#locationShouldContain + */ + @RobotKeyword + @ArgumentNames({ "url" }) public void locationShouldBe(String url) { String actual = getLocation(); if (!actual.equals(url)) { - throw new Selenium2LibraryNonFatalException(String.format( - "Location should have been '%s' but was '%s'", url, actual)); + throw new Selenium2LibraryNonFatalException(String.format("Location should have been '%s', but was '%s'", + url, actual)); } - info(String.format("Current location is '%s'.", url)); + logging.info(String.format("Current location is '%s'.", url)); } + /** + * Verify the current page URL contains url.
+ * + * @param url + * The URL to verify. + * + * @see BrowserManagement#locationShouldBe + */ + @RobotKeyword + @ArgumentNames({ "url" }) public void locationShouldContain(String url) { String actual = getLocation(); if (!actual.contains(url)) { throw new Selenium2LibraryNonFatalException(String.format( - "Location should have been '%s' but was '%s'", url, actual)); + "Location should have contained '%s', but was '%s'", url, actual)); } - info(String.format("Current location is '%s'.", url)); + logging.info(String.format("Current location is '%s'.", url)); } - public String logLocation() { - String actual = getLocation(); - info(actual); - return actual; - } - - public String logSource() { - return logSource("INFO"); + /** + * Verify the current page title is exactly title.
+ * + * @param title + * The title to verify. + * + * @see BrowserManagement#titleShouldNotBe + * @see BrowserManagement#titleShouldContain + * @see BrowserManagement#titleShouldNotContain + */ + @RobotKeyword + @ArgumentNames({ "title" }) + public void titleShouldBe(String title) { + String actual = getTitle(); + if (!actual.equals(title)) { + throw new Selenium2LibraryNonFatalException(String.format("Title should have been '%s', but was '%s'", + title, actual)); + } + logging.info(String.format("Page title is '%s'.", title)); } - public String logSource(String logLevel) { - String actual = getSource(); - log(actual, logLevel); - return actual; + /** + * Verify the current page title is not exactly title.
+ * + * @param title + * The title to verify. + * + * @see BrowserManagement#titleShouldBe + * @see BrowserManagement#titleShouldContain + * @see BrowserManagement#titleShouldNotContain + */ + @RobotKeyword + @ArgumentNames({ "title" }) + public void titleShouldNotBe(String title) { + String actual = getTitle(); + if (actual.equals(title)) { + throw new Selenium2LibraryNonFatalException(String.format("Title should not have been '%s', but was '%s'", + title, actual)); + } + logging.info(String.format("Page title is '%s'.", title)); } - public String logTitle() { + /** + * Verify the current page title contains title.
+ * + * @param title + * The title to verify. + * + * @see BrowserManagement#titleShouldBe + * @see BrowserManagement#titleShouldNotBe + * @see BrowserManagement#titleShouldNotContain + */ + @RobotKeyword + @ArgumentNames({ "title" }) + public void titleShouldContain(String title) { String actual = getTitle(); - info(actual); - return actual; + if (!actual.contains(title)) { + throw new Selenium2LibraryNonFatalException(String.format("Title should have contained '%s', but was '%s'", + title, actual)); + } + logging.info(String.format("Page title is '%s'.", title)); } - public void titleShouldBe(String title) { + /** + * Verify the current page title does not contain title.
+ * + * @param title + * The title to verify. + * + * @see BrowserManagement#titleShouldBe + * @see BrowserManagement#titleShouldNotBe + * @see BrowserManagement#titleShouldContain + */ + @RobotKeyword + @ArgumentNames({ "title" }) + public void titleShouldNotContain(String title) { String actual = getTitle(); - if (!actual.equals(title)) { + if (actual.contains(title)) { throw new Selenium2LibraryNonFatalException(String.format( - "Title should have been '%s' but was '%s'", title, actual)); + "Title should not have contained '%s', but was '%s'", title, actual)); } - info(String.format("Page title is '%s'.", title)); + logging.info(String.format("Page title is '%s'.", title)); } + /** + * Simulates the user clicking the "back" button on their browser.
+ */ + @RobotKeyword public void goBack() { webDriverCache.getCurrent().navigate().back(); } + /** + * Navigates the active browser instance to the provided URL.
+ * + * @param url + * The URL to open. + */ + @RobotKeyword + @ArgumentNames({ "url" }) public void goTo(String url) { - info(String.format("Opening url '%s'", url)); + logging.info(String.format("Opening url '%s'", url)); webDriverCache.getCurrent().get(url); } + /** + * Simulates user reloading page.
+ */ + @RobotKeyword public void reloadPage() { webDriverCache.getCurrent().navigate().refresh(); } + /** + * (NOT IMPLEMENTED) Returns the delay in seconds that is waited + * after each Selenium command.
+ * + * @return The delay in seconds. + * + * @see BrowserManagement#setSeleniumSpeed + */ + @RobotKeyword public String getSeleniumSpeed() { return Robotframework.secsToTimestr(0); } - public String getSeleniumTimeout() { - return Robotframework.secsToTimestr(timeout); - } - - public String getSeleniumImplicitWait() { - return Robotframework.secsToTimestr(implicitWait); - } - + /** + * (NOT IMPLEMENTED) Sets and returns the delay in seconds that is + * waited after each Selenium command.
+ * + * @param timestr + * The delay in seconds. + * @return The previous delay in seconds. + * + * @see BrowserManagement#getSeleniumSpeed + */ + @RobotKeyword("(NOT IMPLEMENTED)\n\nSets the delay in seconds that is waited after each " + "Selenium command.\n") + @ArgumentNames({ "timestr" }) public String setSeleniumSpeed(String timestr) { return "0s"; } + /** + * Returns the timeout in seconds that is used by various keywords.
+ * + * @return The timeout in seconds. + * + * @see BrowserManagement#setSeleniumTimeout + */ + @RobotKeyword + public String getSeleniumTimeout() { + return Robotframework.secsToTimestr(timeout); + } + + /** + * Sets and returns the timeout in seconds that is used by various keywords.
+ *
+ * There are several Wait ... keywords that take a timeout as an argument. + * All of these timeout arguments are optional. The timeout used by all of + * them can be set globally using this keyword. See `Introduction` for more + * information about timeouts.
+ *
+ * The previous timeout value is returned by this keyword and can be used to + * set the old value back later. The default timeout is 5 seconds, but it + * can be altered in importing the library.
+ *
+ * Example: + *
| ${orig timeout} = | + *Set Selenium Timeout | + *15 seconds | + *
| # Open page that loads slowly | + *+ * | + * |
| Set Selenium Timeout | + *${orig timeout} | + *# Reset to old value | + *
+ * + * @return The implicit wait time in seconds. + * + * @see BrowserManagement#setSeleniumImplicitWait + */ + @RobotKeyword + public String getSeleniumImplicitWait() { + return Robotframework.secsToTimestr(implicitWait); + } + + /** + * Sets and returns the implicit wait time in seconds that is used by all + * Selenium 2 WebDriver instances. This affects all currently open and from + * now on opened instances.
+ *
+ * From selenium 2 function: Sets a sticky timeout to implicitly wait for + * an element to be found, or a command to complete. This method only needs + * to be called one time per session.
+ *
+ * Example: + *
| ${orig wait} = | + *Set Selenium Implicit Wait | + *10 seconds | + *
| # Perform AJAX call that is slow | + *+ * | + * |
| Set Selenium Implicit Wait | + *${orig wait} | + *# Reset to old value | + *
+ *
+ * From selenium 2 function: Sets a sticky timeout to implicitly wait for + * an element to be found, or a command to complete. This method only needs + * to be called one time per session.
+ *
+ * Example: + *
| ${orig wait} = | + *Set Browser Implicit Wait | + *10 seconds | + *
| # Perform AJAX call that is slow | + *+ * | + * |
| Set Browser Implicit Wait | + *${orig wait} | + *# Reset to old value | + *
+ *
+ * This is needed to connect to an external Selenium 2 WebDriver rid through + * a local HTTP proxy. This implementation handles BASIC, DIGEST and NTLM + * based authentication schemes correctly.
+ *
+ * The given configuration will be used for all subsequent calls of `Open + * Browser`. To remove the proxy call:
+ * Set Remote Web Driver Proxy | ${EMPTY} | ${EMPTY}
+ *
+ * Some additional info: + *
-
+ *
- If no username is provided, it looks for a username at the + * Java property http.proxyUser and the environment variables HTTP_PROXY and + * http_proxy. If a username is found, it is only used, if the host and port + * also match. + *
- If no password is provided, it looks for a password at the + * Java property http.proxyUser and the environment variables HTTP_PROXY and + * http_proxy. If a password is found, it is only used, if the host, port + * and username also match. + *
- If a domain is provided, NTLM based authentication is used + *
- If no workstation is provided and NTLM based authentication is + * used, the hostname is used as workstation name. + *
+ */ + @RobotKeyword public void deleteAllCookies() { - webDriverCache.getCurrent().manage().deleteAllCookies(); + browserManagement.getCurrentWebDriver().manage().deleteAllCookies(); } + /** + * Deletes cookie matching name.
+ *
+ * If the cookie is not found, nothing happens
+ * + * @param name + * The name of the cookie to delete. + */ + @RobotKeyword + @ArgumentNames({ "name" }) public void deleteCookie(String name) { - webDriverCache.getCurrent().manage().deleteCookieNamed(name); + browserManagement.getCurrentWebDriver().manage().deleteCookieNamed(name); } + /** + * Returns all cookies of the current page.
+ * + * @return All cookies of the current page. + */ + @RobotKeyword public String getCookies() { StringBuffer ret = new StringBuffer(); - ArrayList
+ *
+ * If no cookie is found with name, this keyword fails.
+ * + * @param name + * The name of the cookie + * @return The value of the found cookie + */ + @RobotKeyword + @ArgumentNames({ "name" }) public String getCookieValue(String name) { - org.openqa.selenium.Cookie cookie = webDriverCache.getCurrent() - .manage().getCookieNamed(name); + org.openqa.selenium.Cookie cookie = browserManagement.getCurrentWebDriver().manage().getCookieNamed(name); if (cookie != null) { return cookie.getValue(); } else { - throw new Selenium2LibraryNonFatalException(String.format( - "Cookie with name %s not found.", name)); + throw new Selenium2LibraryNonFatalException(String.format("Cookie with name %s not found.", name)); } } - public void addCookie(String name, String value, String path, - String domain, String secure, String expiry) { + @RobotKeywordOverload + public void addCookie(String name, String value) { + addCookie(name, value, null); + } + + @RobotKeywordOverload + public void addCookie(String name, String value, String path) { + addCookie(name, value, path, null); + } + + @RobotKeywordOverload + public void addCookie(String name, String value, String path, String domain) { + addCookie(name, value, path, domain, ""); + } + + @RobotKeywordOverload + public void addCookie(String name, String value, String path, String domain, String secure) { + addCookie(name, value, path, domain, secure, null); + } + + /** + * Adds a cookie to your current session.
+ * + * @param name + * The name of the cookie. + * @param value + * The cookie value. + * @param path + * Default=NONE. The path the cookie is visible to. + * @param domain + * Default=NONE. The domain the cookie is visible to. + * @param secure + * Default=NONE. Whether this cookie requires a secure + * connection. + * @param expiry + * Default=NONE. The cookie's expiration date + */ + @RobotKeyword + @ArgumentNames({ "name", "value", "path=NONE", "domain=NONE", "secure=NONE", "expiry=NONE" }) + public void addCookie(String name, String value, String path, String domain, String secure, String expiry) { // Parameter expiry not used by Python library - org.openqa.selenium.Cookie cookie = new org.openqa.selenium.Cookie( - name, value, domain, path, null, secure.equals("True")); - webDriverCache.getCurrent().manage().addCookie(cookie); + org.openqa.selenium.Cookie cookie = new org.openqa.selenium.Cookie(name, value, domain, path, null, + "true".equals(secure.toLowerCase())); + browserManagement.getCurrentWebDriver().manage().addCookie(cookie); } } diff --git a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Element.java b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Element.java index 42f177e..00787fd 100644 --- a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Element.java +++ b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Element.java @@ -11,279 +11,840 @@ import org.openqa.selenium.WebDriver; import org.openqa.selenium.WebElement; import org.openqa.selenium.interactions.Actions; +import org.robotframework.javalib.annotation.ArgumentNames; +import org.robotframework.javalib.annotation.Autowired; +import org.robotframework.javalib.annotation.RobotKeyword; +import org.robotframework.javalib.annotation.RobotKeywordOverload; +import org.robotframework.javalib.annotation.RobotKeywords; +import com.github.markusbernhardt.selenium2library.RunOnFailureKeywordsAdapter; import com.github.markusbernhardt.selenium2library.Selenium2LibraryNonFatalException; import com.github.markusbernhardt.selenium2library.locators.ElementFinder; import com.github.markusbernhardt.selenium2library.utils.Python; -public abstract class Element extends Cookie { +@RobotKeywords +public class Element extends RunOnFailureKeywordsAdapter { + + /** + * Instantiated BrowserManagement keyword bean + */ + @Autowired + protected BrowserManagement browserManagement; + + /** + * Instantiated FormElement keyword bean + */ + @Autowired + protected FormElement formElement; + + /** + * Instantiated Logging keyword bean + */ + @Autowired + protected Logging logging; // ############################## // Keywords - Element Lookups // ############################## + @RobotKeywordOverload + @ArgumentNames({ "text" }) public void currentFrameContains(String text) { - this.currentFrameContains(text, "INFO"); - } - + currentFrameContains(text, "INFO"); + } + + /** + * Verify the current frame contains text.
+ *
+ * See `Introduction` for details about log levels.
+ * + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "text", "logLevel=INFO" }) public void currentFrameContains(String text, String logLevel) { if (!isTextPresent(text)) { - log(String.format("Current Frame Contains: %s => FAILED", text), - logLevel); + logging.log(String.format("Current Frame Contains: %s => FAILED", text), logLevel); throw new Selenium2LibraryNonFatalException(String.format( "Page should have contained text '%s', but did not.", text)); } else { - log(String.format("Current Frame Contains: %s => OK", text), - logLevel); + logging.log(String.format("Current Frame Contains: %s => OK", text), logLevel); } } + @RobotKeywordOverload public void currentFrameShouldNotContain(String text) { - this.currentFrameShouldNotContain(text, "INFO"); - } - + currentFrameShouldNotContain(text, "INFO"); + } + + /** + * Verify the current frame does not contain text.
+ *
+ * See `Introduction` for details about log levels.
+ * + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "text", "logLevel=INFO" }) public void currentFrameShouldNotContain(String text, String logLevel) { if (isTextPresent(text)) { - log(String.format("Current Frame Should Not Contain: %s => FAILED", text), - logLevel); + logging.log(String.format("Current Frame Should Not Contain: %s => FAILED", text), logLevel); throw new Selenium2LibraryNonFatalException(String.format( "Page should have not contained text '%s', but did.", text)); } else { - log(String.format("Current Frame Should Not Contain: %s => OK", text), - logLevel); + logging.log(String.format("Current Frame Should Not Contain: %s => OK", text), logLevel); } } - public void elementShouldContain(String locator, String expected) { - this.elementShouldContain(locator, expected, ""); + @RobotKeywordOverload + public void elementShouldContain(String locator, String text) { + elementShouldContain(locator, text, ""); + } + + /** + * Verify the element identified by locator contains text.
+ *
+ * See `Introduction` for details about locators. + * + * @param locator + * The locator to locate the element. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void elementShouldContain(String locator, String text, String message) { + String actual = getText(locator); + + if (!actual.toLowerCase().contains(text.toLowerCase())) { + logging.info(String.format("Element Should Contain: %s => FAILED", text)); + throw new Selenium2LibraryNonFatalException(String.format( + "Element should have contained text '%s', but its text was %s.", text, actual)); + } else { + logging.info(String.format("Element Should Contain: %s => OK", text)); + } } - public void elementShouldContain(String locator, String expected, - String message) { - String actual = fetchText(locator); - - if (!actual.toLowerCase().contains(expected.toLowerCase())) { - info(String - .format("Element Should Contain: %s => FAILED", expected)); - throw new Selenium2LibraryNonFatalException( - String.format( - "Element should have contained text '%s' but its text was %s.", - expected, actual)); + @RobotKeywordOverload + public void elementShouldNotContain(String locator, String text) { + elementShouldNotContain(locator, text, ""); + } + + /** + * Verify the element identified by locator does not contain + * text.
+ *
+ * See `Introduction` for details about locators. + * + * @param locator + * The locator to locate the element. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void elementShouldNotContain(String locator, String text, String message) { + String actual = getText(locator); + + if (actual.toLowerCase().contains(text.toLowerCase())) { + logging.info(String.format("Element Should Not Contain: %s => FAILED", text)); + throw new Selenium2LibraryNonFatalException(String.format( + "Element should not have contained text '%s', but its text was %s.", text, actual)); } else { - info(String.format("Element Should Contain: %s => OK", expected)); + logging.info(String.format("Element Should Not Contain: %s => OK", text)); } } + @RobotKeywordOverload public void frameShouldContain(String locator, String text) { - this.frameShouldContain(locator, text, "INFO"); - } - + frameShouldContain(locator, text, "INFO"); + } + + /** + * Verify the frame identified by locator contains text.
+ *
+ * See `Introduction` for details about locators. + * + * @param locator + * The locator to locate the frame. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "logLevel=INFO" }) public void frameShouldContain(String locator, String text, String logLevel) { if (!frameContains(locator, text)) { - log(String.format("Frame Should Contain: %s => FAILED", text), - logLevel); + logging.log(String.format("Frame Should Contain: %s => FAILED", text), logLevel); throw new Selenium2LibraryNonFatalException(String.format( - "Frame should have contained text '%s' but did not.", text)); + "Frame should have contained text '%s', but did not.", text)); } else { - log(String.format("Frame Should Contain: %s => OK", text), logLevel); + logging.log(String.format("Frame Should Contain: %s => OK", text), logLevel); } } - public void pageShouldContain(String text) { - this.pageShouldContain(text, "INFO"); + /** + * Verify the frame identified by locator does not contain + * text.
+ *
+ * See `Introduction` for details about locators. + * + * @param locator + * The locator to locate the frame. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "logLevel=INFO" }) + public void frameShouldNotContain(String locator, String text, String logLevel) { + if (frameContains(locator, text)) { + logging.log(String.format("Frame Should Not Contain: %s => FAILED", text), logLevel); + throw new Selenium2LibraryNonFatalException(String.format( + "Frame should not have contained text '%s', but did.", text)); + } else { + logging.log(String.format("Frame Should Not Contain: %s => OK", text), logLevel); + } } + @RobotKeywordOverload + public void pageShouldContain(String text) { + pageShouldContain(text, "INFO"); + } + + /** + * Verify the current page contains text.
+ *
+ * See `Introduction` for details about log levels.
+ * + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "text", "logLevel=INFO" }) public void pageShouldContain(String text, String logLevel) { if (!pageContains(text)) { - log(String.format("Page Should Contain: %s => FAILED", text), - logLevel); + logging.log(String.format("Page Should Contain: %s => FAILED", text), logLevel); throw new Selenium2LibraryNonFatalException(String.format( "Page should have contained text '%s' but did not.", text)); } else { - log(String.format("Page Should Contain: %s => OK", text), logLevel); + logging.log(String.format("Page Should Contain: %s => OK", text), logLevel); } } - public void pageShouldContainElement(String locator) { - this.pageShouldContainElement(locator, "", "INFO"); - } - - public void pageShouldContainElement(String locator, String message) { - this.pageShouldContainElement(locator, message, "INFO"); - } - - public void pageShouldContainElement(String locator, String message, - String logLevel) { - this.pageShouldContainElement(locator, null, message, "INFO"); - } - - public void pageShouldContainElement(String locator, String tag, - String message, String logLevel) { - helperPageShouldContainElement(locator, tag, message, logLevel); - } - + @RobotKeywordOverload public void pageShouldNotContain(String text) { - this.pageShouldNotContain(text, "INFO"); - } - + pageShouldNotContain(text, "INFO"); + } + + /** + * Verify the current page does not contain text.
+ *
+ * See `Introduction` for details about log levels.
+ * + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "text", "logLevel=INFO" }) public void pageShouldNotContain(String text, String logLevel) { if (pageContains(text)) { - log(String.format("Page Should Not Contain: %s => FAILED", text), - logLevel); + logging.log(String.format("Page Should Not Contain: %s => FAILED", text), logLevel); throw new Selenium2LibraryNonFatalException(String.format( "Page should not have contained text '%s' but did.", text)); } else { - log(String.format("Page Should Not Contain: %s => OK", text), - logLevel); + logging.log(String.format("Page Should Not Contain: %s => OK", text), logLevel); } } - public void pageShouldNotContainElement(String locator) { - this.pageShouldNotContainElement(locator, "", "INFO"); + @RobotKeywordOverload + public void pageShouldContainElement(String locator) { + pageShouldContainElement(locator, "", "INFO"); } - public void pageShouldNotContainElement(String locator, String message) { - this.pageShouldNotContainElement(locator, message, "INFO"); + @RobotKeywordOverload + public void pageShouldContainElement(String locator, String message) { + pageShouldContainElement(locator, message, "INFO"); + } + + /** + * Verify the element identified by locator is found on the current + * page.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about log levels and locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainElement(String locator, String message, String logLevel) { + pageShouldContainElement(locator, null, message, "INFO"); + } + + protected void pageShouldContainElement(String locator, String tag, String message, String logLevel) { + String name = tag != null ? tag : "element"; + if (!isElementPresent(locator, tag)) { + if (message == null || message.equals("")) { + message = String.format("Page should have contained %s '%s' but did not", name, locator); + } + logging.log(message, logLevel); + throw new Selenium2LibraryNonFatalException(message); + } else { + logging.log(String.format("Current page contains %s '%s'.", name, locator), logLevel); + } } - public void pageShouldNotContainElement(String locator, String message, - String logLevel) { - this.pageShouldNotContainElement(locator, null, message, "INFO"); + @RobotKeywordOverload + public void pageShouldNotContainElement(String locator) { + pageShouldNotContainElement(locator, "", "INFO"); } - public void pageShouldNotContainElement(String locator, String tag, - String message, String logLevel) { - helperPageShouldNotContainElement(locator, tag, message, logLevel); + @RobotKeywordOverload + public void pageShouldNotContainElement(String locator, String message) { + pageShouldNotContainElement(locator, message, "INFO"); + } + + /** + * Verify the element identified by locator is not found on the + * current page.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about log levels and locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainElement(String locator, String message, String logLevel) { + pageShouldNotContainElement(locator, null, message, "INFO"); + } + + protected void pageShouldNotContainElement(String locator, String tag, String message, String logLevel) { + String name = tag != null ? tag : "element"; + if (isElementPresent(locator, tag)) { + if (message == null || message.equals("")) { + message = String.format("Page should not have contained %s '%s' but did", name, locator); + } + logging.log(message, logLevel); + throw new Selenium2LibraryNonFatalException(message); + } else { + logging.log(String.format("Current page does not contain %s '%s'.", name, locator), logLevel); + } } // ############################## // Keywords - Attributes // ############################## + /** + * Assigns a temporary identifier to the element identified by + * locator
+ *
+ * This is mainly useful, when the locator is a complicated and slow XPath + * expression. The identifier expires when the page is reloaded.
+ *
+ * Example: + *
| Assign ID to Element | + *xpath=//div[@id=\"first_div\"] | + *my id | + *
| Page Should Contain Element | + *my id | + *+ * |
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) + public void elementShouldBeEnabled(String locator) { + if (!isEnabled(locator)) { + throw new Selenium2LibraryNonFatalException(String.format("Element %s is disabled.", locator)); + } + } + + /** + * Verify the element identified by locator is disabled.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void elementShouldBeDisabled(String locator) { if (isEnabled(locator)) { - throw new Selenium2LibraryNonFatalException(String.format( - "Element %s is enabled.", locator)); + throw new Selenium2LibraryNonFatalException(String.format("Element %s is enabled.", locator)); } } - public void elementShouldBeEnabled(String locator) { - if (!isEnabled(locator)) { - throw new Selenium2LibraryNonFatalException(String.format( - "Element %s is disabled.", locator)); + @RobotKeywordOverload + public void elementShouldBeSelected(String locator) { + elementShouldBeSelected(locator, ""); + } + + /** + * Verify the element identified by locator is selected.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) + public void elementShouldBeSelected(String locator, String message) { + logging.info(String.format("Verifying element '%s' is selected.", locator)); + boolean selected = isSelected(locator); + + if (!selected) { + if (message == null || message.equals("")) { + message = String.format("Element '%s' should be selected, but it is not.", locator); + } + throw new Selenium2LibraryNonFatalException(message); } } - public void elementShouldBeVisible(String locator) { - this.elementShouldBeVisible(locator, ""); + @RobotKeywordOverload + public void elementShouldNotBeSelected(String locator) { + elementShouldNotBeSelected(locator, ""); + } + + /** + * Verify the element identified by locator is not selected.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) + public void elementShouldNotBeSelected(String locator, String message) { + logging.info(String.format("Verifying element '%s' is not selected.", locator)); + boolean selected = isSelected(locator); + + if (selected) { + if (message == null || message.equals("")) { + message = String.format("Element '%s' should not be selected, but it is.", locator); + } + throw new Selenium2LibraryNonFatalException(message); + } } + @RobotKeywordOverload + public void elementShouldBeVisible(String locator) { + elementShouldBeVisible(locator, ""); + } + + /** + * Verify the element identified by locator is visible.
+ *
+ * Herein, visible means that the element is logically visible, not + * optically visible in the current browser viewport. For example, an + * element that carries display:none is not logically visible, so using this + * keyword on that element would fail.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) public void elementShouldBeVisible(String locator, String message) { - info(String.format("Verifying element '%s' is visible.", locator)); + logging.info(String.format("Verifying element '%s' is visible.", locator)); boolean visible = isVisible(locator); if (!visible) { if (message == null || message.equals("")) { - message = String.format( - "Element '%s' should be visible, but it is not.", - locator); + message = String.format("Element '%s' should be visible, but it is not.", locator); } throw new Selenium2LibraryNonFatalException(message); } } + @RobotKeywordOverload public void elementShouldNotBeVisible(String locator) { - this.elementShouldNotBeVisible(locator, ""); - } - + elementShouldNotBeVisible(locator, ""); + } + + /** + * Verify the element identified by locator is not visible.
+ *
+ * Herein, visible means that the element is logically visible, not + * optically visible in the current browser viewport. For example, an + * element that carries display:none is not logically visible, so using this + * keyword on that element would fail.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) public void elementShouldNotBeVisible(String locator, String message) { - info(String.format("Verifying element '%s' is not visible.", locator)); + logging.info(String.format("Verifying element '%s' is not visible.", locator)); boolean visible = isVisible(locator); if (visible) { if (message == null || message.equals("")) { - message = String.format( - "Element '%s' should not be visible, but it is.", - locator); + message = String.format("Element '%s' should not be visible, but it is.", locator); } throw new Selenium2LibraryNonFatalException(message); } } - public void elementTextShouldBe(String locator, String expected) { - this.elementTextShouldBe(locator, expected, ""); + @RobotKeywordOverload + public void elementShouldBeClickable(String locator) { + elementShouldBeClickable(locator, ""); + } + + /** + * Verify the element identified by locator is clickable.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) + public void elementShouldBeClickable(String locator, String message) { + logging.info(String.format("Verifying element '%s' is clickable.", locator)); + boolean clickable = isClickable(locator); + + if (!clickable) { + if (message == null || message.equals("")) { + message = String.format("Element '%s' should be clickable, but it is not.", locator); + } + throw new Selenium2LibraryNonFatalException(message); + } + } + + @RobotKeywordOverload + public void elementShouldNotBeClickable(String locator) { + elementShouldNotBeClickable(locator, ""); + } + + /** + * Verify the element identified by locator is not clickable.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE" }) + public void elementShouldNotBeClickable(String locator, String message) { + logging.info(String.format("Verifying element '%s' is not clickable.", locator)); + boolean clickable = isClickable(locator); + + if (clickable) { + if (message == null || message.equals("")) { + message = String.format("Element '%s' should not be clickable, but it is.", locator); + } + throw new Selenium2LibraryNonFatalException(message); + } } - public void elementTextShouldBe(String locator, String expected, - String message) { - info(String.format( - "Verifying element '%s' contains exactly text '%s'.", locator, - expected)); + @RobotKeywordOverload + public void elementTextShouldBe(String locator, String expected) { + elementTextShouldBe(locator, expected, ""); + } + + /** + * Verify the text of the element identified by locator is exactly + * text.
+ *
+ * In contrast to `Element Should Contain`, this keyword does not try a + * substring match but an exact match on the element identified by locator.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void elementTextShouldBe(String locator, String text, String message) { + List
+ *
+ * In contrast to `Element Should Not Contain`, this keyword does not try a + * substring match but an exact match on the element identified by locator.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void elementTextShouldNotBe(String locator, String text, String message) { List
+ *
+ * The attribute_locator consists of element locator followed by an @ + * sign and attribute name. Example: element_id@class
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param attributeLocator + * The attribute locator. + * @return The attribute value. + */ + @RobotKeyword + @ArgumentNames({ "attributeLocator" }) public String getElementAttribute(String attributeLocator) { String[] parts = parseAttributeLocator(attributeLocator); List
+ *
+ * This keyword does not execute any checks on whether or not the clear + * method has succeeded, so if any subsequent checks are needed, they should + * be executed using method `Element Text Should Be`.
+ *
+ * Also, this method will use WebDriver's internal _element.clear()_ method, + * i.e. it will not send any keypresses, and it will not have any effect + * whatsoever on elements other than input textfields or input textareas. + * Clients relying on keypresses should implement their own methods.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) + public void clearElementText(String locator) { + List
+ *
+ * The position is returned in pixels off the left side of the page, as an + * integer. Fails if the matching element is not found.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @return The horizontal position + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public int getHorizontalPosition(String locator) { List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @return The value attribute of the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public String getValue(String locator) { return getValue(locator, null); } - public String getValue(String locator, String tag) { - return this.fetchValue(locator, tag); + protected String getValue(String locator, String tag) { + List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @return The text of the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public String getText(String locator) { - return fetchText(locator); + List
+ *
+ * The position is returned in pixels off the top of the page, as an + * integer. Fails if the matching element is not found.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @return The vertical position + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public int getVerticalPosition(String locator) { List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void clickElement(String locator) { - info(String.format("Clicking element '%s'.", locator)); + logging.info(String.format("Clicking element '%s'.", locator)); List
+ *
+ * The cursor is moved at the center of the element and the to the given x/y + * offset from that point. Both offsets are specified as negative (left/up) + * or positive (right/down) number.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ *
+ * + * @param locator + * The locator to locate the element. + * @param xOffset + * The horizontal offset in pixel. Negative means left, positive + * right. + * @param yOffset + * The vertical offset in pixel. Negative means up, positive + * down. + */ + @RobotKeyword + @ArgumentNames({ "locator", "xOffset", "yOffset" }) + public void clickElementAtCoordinates(String locator, String xOffset, String yOffset) { + logging.info(String.format("Clicking element '%s'in coordinates '%s', '%s'.", locator, xOffset, yOffset)); + List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void doubleClickElement(String locator) { - info(String.format("Double clicking element '%s'.", locator)); + logging.info(String.format("Double clicking element '%s'.", locator)); List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void focus(String locator) { List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ *
+ * Example: + *
| Drag And Drop | + *elem1 | + *elem2 | + *# Move elem1 over elem2 | + *
+ *
+ * Both offsets are specified as negative (left/up) or positive (right/down) + * number.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ *
+ * Example: + *
| Drag And Drop By Offset | + *elem1 | + *50 | + *35 | + *# Move elem1 50px right and 35px down. | + *
+ *
+ * The element is pressed without releasing the mouse button.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @see Element#mouseDownOnImage + * @see Element#mouseDownOnLink + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseDown(String locator) { - info(String.format("Simulating Mouse Down on element '%s'.", locator)); + logging.info(String.format("Simulating Mouse Down on element '%s'.", locator)); List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseOut(String locator) { - info(String.format("Simulating Mouse Out on element '%s'.", locator)); + logging.info(String.format("Simulating Mouse Out on element '%s'.", locator)); List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseOver(String locator) { - info(String.format("Simulating Mouse Over on element '%s'.", locator)); + logging.info(String.format("Simulating Mouse Over on element '%s'.", locator)); List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseUp(String locator) { - info(String.format("Simulating Mouse Up on element '%s'.", locator)); + logging.info(String.format("Simulating Mouse Up on element '%s'.", locator)); List
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void openContextMenu(String locator) { List
+ *
+ * This keyword is especially useful, when the element has an OnEvent + * handler that needs to be explicitly invoked.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @param event + * The event to invoke. + */ + @RobotKeyword + @ArgumentNames({ "locator", "event" }) public void simulate(String locator, String event) { List
+ *
+ * Key is either a single character, or a numerical ASCII code of the key + * lead by '\\'.
+ *
+ * Key attributes for arbitrary elements are id and name. See `Introduction` + * for details about locators.
+ *
+ * Example: + *
| Press Key | + *text_field | + *q | + *# Press 'q' | + *
| Press Key | + *login_button | + *\\13 | + *# ASCII code for enter key | + *
+ *
+ * Key attributes for links are id, name, href and link text. See + * `Introduction` for details about locators.
+ * + * @param locator + * The locator to locate the link. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void clickLink(String locator) { - info(String.format("Clicking link '%s'.", locator)); + logging.info(String.format("Clicking link '%s'.", locator)); List
+ *
+ * If a link has no id, an empty string will be in the list instead.
+ * + * @return The list of link ids. + */ + @RobotKeyword public ArrayList
+ *
+ * The element is pressed without releasing the mouse button.
+ *
+ * Key attributes for links are id, name, href and link text. See + * `Introduction` for details about locators.
+ * + * @param locator + * The locator to locate the element. + * @see Element#mouseDown + * @see Element#mouseDownOnImage + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseDownOnLink(String locator) { List
+ *
+ * Key attributes for links are id, name, href and link text. See + * `Introduction` for details about log levels and locators.
+ * + * @param locator + * The locator to locate the link. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainLink(String locator, String message, String logLevel) { + pageShouldContainElement(locator, "link", message, logLevel); + } + + @RobotKeywordOverload public void pageShouldNotContainLink(String locator) { - this.pageShouldNotContainLink(locator, "", "INFO"); + pageShouldNotContainLink(locator, "", "INFO"); } + @RobotKeywordOverload public void pageShouldNotContainLink(String locator, String message) { - this.pageShouldNotContainLink(locator, message, "INFO"); - } - - public void pageShouldNotContainLink(String locator, String message, - String logLevel) { - this.pageShouldNotContainElement(locator, "link", message, logLevel); + pageShouldNotContainLink(locator, message, "INFO"); + } + + /** + * Verify the link identified by locator is not found on the current + * page.
+ *
+ * Key attributes for links are id, name, href and link text. See + * `Introduction` for details about log levels and locators.
+ * + * @param locator + * The locator to locate the link. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainLink(String locator, String message, String logLevel) { + pageShouldNotContainElement(locator, "link", message, logLevel); } // ############################## // Keywords - Images // ############################## + /** + * Click on the image identified by locator.
+ *
+ * Key attributes for images are id, src and alt. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the element. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void clickImage(String locator) { - info(String.format("Clicking image '%s'.", locator)); + logging.info(String.format("Clicking image '%s'.", locator)); List
+ *
+ * The element is pressed without releasing the mouse button.
+ *
+ * Key attributes for images are id, src and alt. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the element. + * @see Element#mouseDown + * @see Element#mouseDownOnLink + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void mouseDownOnImage(String locator) { List
+ *
+ * Key attributes for images are id, src and alt. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the link. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainImage(String locator, String message, String logLevel) { pageShouldContainElement(locator, "image", message, logLevel); } + @RobotKeywordOverload + @ArgumentNames({ "locator" }) public void pageShouldNotContainImage(String locator) { - this.pageShouldNotContainImage(locator, "", "INFO"); + pageShouldNotContainImage(locator, "", "INFO"); } + @RobotKeywordOverload + @ArgumentNames({ "locator", "message=NONE" }) public void pageShouldNotContainImage(String locator, String message) { - this.pageShouldNotContainImage(locator, message, "INFO"); - } - - public void pageShouldNotContainImage(String locator, String message, - String logLevel) { + pageShouldNotContainImage(locator, message, "INFO"); + } + + /** + * Verify the image identified by locator is not found on the current + * page.
+ *
+ * Key attributes for images are id, src and alt. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the link. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainImage(String locator, String message, String logLevel) { pageShouldNotContainElement(locator, "image", message, logLevel); } @@ -528,6 +1449,18 @@ public void pageShouldNotContainImage(String locator, String message, // Keywords - Xpath // ############################## + /** + * Returns the number of elements located the given xpath.
+ *
+ * If you wish to assert the number of located elements, use `Xpath Should + * Match X Times`.
+ * + * @param xpath + * The XPath to match page elements + * @return The number of located elements + */ + @RobotKeyword + @ArgumentNames({ "xpath" }) public int getMatchingXpathCount(String xpath) { if (!xpath.startsWith("xpath=")) { xpath = "xpath=" + xpath; @@ -537,17 +1470,34 @@ public int getMatchingXpathCount(String xpath) { return elements.size(); } + @RobotKeywordOverload + @ArgumentNames({ "xpath", "expectedXpathCount" }) public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount) { - this.xpathShouldMatchXTimes(xpath, expectedXpathCount, ""); - } - - public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount, - String message) { - this.xpathShouldMatchXTimes(xpath, expectedXpathCount, message, "INFO"); - } - - public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount, - String message, String logLevel) { + xpathShouldMatchXTimes(xpath, expectedXpathCount, ""); + } + + @RobotKeywordOverload + @ArgumentNames({ "xpath", "expectedXpathCount", "message=NONE" }) + public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount, String message) { + xpathShouldMatchXTimes(xpath, expectedXpathCount, message, "INFO"); + } + + /** + * Verify that the page contains the expectedXpathCount of elements + * located by the given xpath.
+ * + * @param xpath + * The XPath to match page elements + * @param expectedXpathCount + * The expected number of located elements + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "xpath", "expectedXpathCount", "message=NONE", "logLevel=INFO" }) + public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount, String message, String logLevel) { if (!xpath.startsWith("xpath=")) { xpath = "xpath=" + xpath; } @@ -556,37 +1506,30 @@ public void xpathShouldMatchXTimes(String xpath, int expectedXpathCount, if (actualXpathCount != expectedXpathCount) { if (message == null || message.equals("")) { - message = String - .format("Xpath %s should have matched %s times but matched %s times.", - xpath, expectedXpathCount, actualXpathCount); + message = String.format("Xpath %s should have matched %s times but matched %s times.", xpath, + expectedXpathCount, actualXpathCount); } throw new Selenium2LibraryNonFatalException(message); } - log(String.format("Current page contains %s elements matching '%s'.", - actualXpathCount, xpath), logLevel); + logging.log(String.format("Current page contains %s elements matching '%s'.", actualXpathCount, xpath), + logLevel); } // ############################## // Internal Methods // ############################## - @Override - protected List
+ *
+ * If the locator is empty, the first form in the page will be submitted.
+ *
+ * Key attributes for forms are id and name. See `Introduction` for details + * about locators.
+ * + * @param locator + * Default=NONE. The locator to locate the form. + */ + @RobotKeyword + @ArgumentNames({ "locator=NONE" }) public void submitForm(String locator) { - info(String.format("Submitting form '%s'.", locator)); + logging.info(String.format("Submitting form '%s'.", locator)); if (locator == null) { locator = "xpath=//form"; } - List
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the checkbox. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void checkboxShouldBeSelected(String locator) { - info(String.format("Verifying checkbox '%s' is selected.", locator)); + logging.info(String.format("Verifying checkbox '%s' is selected.", locator)); WebElement element = getCheckbox(locator); if (!element.isSelected()) { - throw new Selenium2LibraryNonFatalException(String.format( - "Checkbox '%s' should have been selected.", locator)); + throw new Selenium2LibraryNonFatalException(String.format("Checkbox '%s' should have been selected.", + locator)); } } + /** + * Verify the checkbox identified by locator is not selected/checked.
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the checkbox. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void checkboxShouldNotBeSelected(String locator) { - info(String.format("Verifying checkbox '%s' is selected.", locator)); + logging.info(String.format("Verifying checkbox '%s' is selected.", locator)); WebElement element = getCheckbox(locator); if (element.isSelected()) { - throw new Selenium2LibraryNonFatalException(String.format( - "Checkbox '%s' should not have been selected.", locator)); + throw new Selenium2LibraryNonFatalException(String.format("Checkbox '%s' should not have been selected.", + locator)); } } + @RobotKeywordOverload public void pageShouldContainCheckbox(String locator) { pageShouldContainCheckbox(locator, ""); } + @RobotKeywordOverload public void pageShouldContainCheckbox(String locator, String message) { pageShouldContainCheckbox(locator, message, "INFO"); } - public void pageShouldContainCheckbox(String locator, String message, - String loglevel) { - pageShouldContainElement(locator, "checkbox", message, loglevel); - } - + /** + * Verify the checkbox identified by locator is found on the current + * page.
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the checkbox. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainCheckbox(String locator, String message, String logLevel) { + element.pageShouldContainElement(locator, "checkbox", message, logLevel); + } + + @RobotKeywordOverload public void pageShouldNotContainCheckbox(String locator) { pageShouldNotContainCheckbox(locator, ""); } + @RobotKeywordOverload public void pageShouldNotContainCheckbox(String locator, String message) { pageShouldNotContainCheckbox(locator, message, "INFO"); } - public void pageShouldNotContainCheckbox(String locator, String message, - String loglevel) { - pageShouldNotContainElement(locator, "checkbox", message, loglevel); - } - + /** + * Verify the checkbox identified by locator is not found on the + * current page.
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the checkbox. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainCheckbox(String locator, String message, String logLevel) { + element.pageShouldNotContainElement(locator, "checkbox", message, logLevel); + } + + /** + * Select the checkbox identified by locator.
+ *
+ * Does nothing, if the checkbox is already selected.
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the checkbox. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void selectCheckbox(String locator) { - info(String.format("Selecting checkbox '%s'.", locator)); + logging.info(String.format("Selecting checkbox '%s'.", locator)); WebElement element = getCheckbox(locator); if (!element.isSelected()) { element.click(); } } + /** + * Unselect the checkbox identified by locator.
+ *
+ * Does nothing, if the checkbox is not selected.
+ *
+ * Key attributes for checkboxes are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the checkbox. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void unselectCheckbox(String locator) { - info(String.format("Selecting checkbox '%s'.", locator)); + logging.info(String.format("Selecting checkbox '%s'.", locator)); WebElement element = getCheckbox(locator); if (element.isSelected()) { element.click(); } } + @RobotKeywordOverload public void pageShouldContainRadioButton(String locator) { pageShouldContainRadioButton(locator, ""); } + @RobotKeywordOverload public void pageShouldContainRadioButton(String locator, String message) { pageShouldContainRadioButton(locator, message, "INFO"); } - public void pageShouldContainRadioButton(String locator, String message, - String loglevel) { - pageShouldContainElement(locator, "radio button", message, loglevel); - } - + /** + * Verify the radio button identified by locator is found on the + * current page.
+ *
+ * Key attributes for radio buttons are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the radio button. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainRadioButton(String locator, String message, String logLevel) { + element.pageShouldContainElement(locator, "radio button", message, logLevel); + } + + @RobotKeywordOverload public void pageShouldNotContainRadioButton(String locator) { pageShouldNotContainRadioButton(locator, ""); } + @RobotKeywordOverload public void pageShouldNotContainRadioButton(String locator, String message) { pageShouldNotContainRadioButton(locator, message, "INFO"); } - public void pageShouldNotContainRadioButton(String locator, String message, - String loglevel) { - pageShouldNotContainElement(locator, "radio button", message, loglevel); - } - + /** + * Verify the radio button identified by locator is not found on the + * current page.
+ *
+ * Key attributes for radio buttons are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the radio button. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainRadioButton(String locator, String message, String logLevel) { + element.pageShouldNotContainElement(locator, "radio button", message, logLevel); + } + + /** + * Verify the radio button group identified by groupName has its + * selection set to value.
+ *
+ * See `Select Radio Button` for details about locating radio buttons.
+ * + * @param groupName + * The radio button group name. + * @param value + * The expected value. + */ + @RobotKeyword + @ArgumentNames({ "groupName", "value" }) public void radioButtonShouldBeSetTo(String groupName, String value) { - info(String.format("Verifying radio button '%s' has selection '%s'.", - groupName, value)); + logging.info(String.format("Verifying radio button '%s' has selection '%s'.", groupName, value)); List
+ *
+ * See `Select Radio Button` for details about locating radio buttons.
+ * + * @param groupName + * The radio button group name. + */ + @RobotKeyword + @ArgumentNames({ "groupName" }) public void radioButtonShouldNotBeSelected(String groupName) { - info(String.format("Verifying radio button '%s' has no selection.", - groupName)); + logging.info(String.format("Verifying radio button '%s' has no selection.", groupName)); List
+ *
+ * Example: + *
| Select Radio Button | + *size | + *XL | + *# Matches HTML like <input type="radio" name="size" + * value="XL">XL</input> | + *
| Select Radio Button | + *size | + *sizeXL | + *# Matches HTML like <input type="radio" name="size" value="XL" + * id="sizeXL">XL</input> | + *
+ *
+ * This keyword is most often used to input files into upload forms. The + * file specified with filePath must be available on the same host where the + * Selenium Server is running.
+ *
+ * Example: + *
| Choose File | + *my_upload_field | + */home/user/files/trades.csv | + *
+ * + * @param locator + * The locator to locate the input field. + * @param filePath + * The file path to input + */ + @RobotKeyword + @ArgumentNames({ "locator", "filePath" }) public void chooseFile(String locator, String filePath) { if (!new File(filePath).isFile()) { - info(String.format( - "File '%s' does not exist on the local file system", - filePath)); + logging.info(String.format("File '%s' does not exist on the local file system", filePath)); } - elementFind(locator, true, true).get(0).sendKeys(filePath); - } - + element.elementFind(locator, true, true).get(0).sendKeys(filePath); + } + + /** + * Types the given text into the password field identified by + * locator.
+ *
+ * Key attributes for input fields are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the password field. + * @param text + * The password to input + */ + @RobotKeyword + @ArgumentNames({ "locator", "text" }) public void inputPassword(String locator, String text) { - info(String.format("Typing password into text field '%s'", locator)); + logging.info(String.format("Typing password into text field '%s'", locator)); inputTextIntoTextField(locator, text); } + /** + * Types the given text into the text field identified by + * locator.
+ *
+ * Key attributes for input fields are id and name. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the text field. + * @param text + * The password to input + */ + @RobotKeyword + @ArgumentNames({ "locator", "text" }) public void inputText(String locator, String text) { - info(String.format("Typing text '%s' into text field '%s'", text, - locator)); + logging.info(String.format("Typing text '%s' into text field '%s'", text, locator)); inputTextIntoTextField(locator, text); } + @RobotKeywordOverload public void pageShouldContainTextfield(String locator) { pageShouldContainTextfield(locator, ""); } + @RobotKeywordOverload public void pageShouldContainTextfield(String locator, String message) { pageShouldContainTextfield(locator, message, "INFO"); } - public void pageShouldContainTextfield(String locator, String message, - String loglevel) { - pageShouldContainElement(locator, "text field", message, loglevel); - } - + /** + * Verify the text field identified by locator is found on the + * current page.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainTextfield(String locator, String message, String logLevel) { + element.pageShouldContainElement(locator, "text field", message, logLevel); + } + + @RobotKeywordOverload public void pageShouldNotContainTextfield(String locator) { pageShouldNotContainTextfield(locator, ""); } + @RobotKeywordOverload public void pageShouldNotContainTextfield(String locator, String message) { pageShouldNotContainTextfield(locator, message, "INFO"); } - public void pageShouldNotContainTextfield(String locator, String message, - String loglevel) { - pageShouldNotContainElement(locator, "text field", message, loglevel); - } - - public void textfieldShouldContain(String locator, String expected) { - textfieldShouldContain(locator, expected, ""); - } - - public void textfieldShouldContain(String locator, String expected, - String message) { - String actual = getValue(locator, "text field"); - if (!actual.contains(expected)) { + /** + * Verify the text field identified by locator is not found on the + * current page.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainTextfield(String locator, String message, String logLevel) { + element.pageShouldNotContainElement(locator, "text field", message, logLevel); + } + + @RobotKeywordOverload + public void textfieldValueShouldBe(String locator, String text) { + textfieldValueShouldBe(locator, text, ""); + } + + /** + * Verify the text field identified by locator is exactly + * text.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textfieldShouldContain + * @see FormElement#textfieldShouldNotContain + * @see FormElement#textfieldValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textfieldValueShouldBe(String locator, String text, String message) { + String actual = element.getValue(locator, "text field"); + if (!actual.contains(text)) { if (message == null) { - message = String - .format("Text field '%s' should have contained text '%s' but it contained '%s'", - locator, expected, actual); + message = String.format("Value of text field '%s' should have been '%s' but was '%s'", locator, text, + actual); } throw new Selenium2LibraryNonFatalException(message); } - info(String.format("Text field '%s' contains text '%s'.", locator, - expected)); - } - - public void textfieldValueShouldBe(String locator, String expected) { - textfieldValueShouldBe(locator, expected, ""); - } - - public void textfieldValueShouldBe(String locator, String expected, - String message) { - String actual = getValue(locator, "text field"); - if (!actual.contains(expected)) { + logging.info(String.format("Content of text field '%s' is '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textfieldValueShouldNotBe(String locator, String text) { + textfieldValueShouldNotBe(locator, text, ""); + } + + /** + * Verify the text field identified by locator is not exactly + * text.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textfieldShouldContain + * @see FormElement#textfieldShouldNotContain + * @see FormElement#textfieldValueShouldBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textfieldValueShouldNotBe(String locator, String text, String message) { + String actual = element.getValue(locator, "text field"); + if (actual.contains(text)) { if (message == null) { - message = String - .format("Value of text field '%s' should have been '%s' but was '%s'", - locator, expected, actual); + message = String.format("Value of text field '%s' should not have been '%s' but was '%s'", locator, + text, actual); } throw new Selenium2LibraryNonFatalException(message); } - info(String.format("Content of text field '%s' is '%s'.", locator, - expected)); - } - + logging.info(String.format("Content of text field '%s' is '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textfieldShouldContain(String locator, String text) { + textfieldShouldContain(locator, text, ""); + } + + /** + * Verify the text field identified by locator contains text.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textfieldShouldNotContain + * @see FormElement#textfieldValueShouldBe + * @see FormElement#textfieldValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textfieldShouldContain(String locator, String text, String message) { + String actual = element.getValue(locator, "text field"); + if (!actual.contains(text)) { + if (message == null) { + message = String.format("Text field '%s' should have contained text '%s', but was '%s'", locator, text, + actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Text field '%s' contains text '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textfieldShouldNotContain(String locator, String text) { + textfieldShouldNotContain(locator, text, ""); + } + + /** + * Verify the text field identified by locator does not contain + * text.
+ *
+ * Key attributes for text field are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text field. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textfieldShouldContain + * @see FormElement#textfieldValueShouldBe + * @see FormElement#textfieldValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textfieldShouldNotContain(String locator, String text, String message) { + String actual = element.getValue(locator, "text field"); + if (actual.contains(text)) { + if (message == null) { + message = String.format("Text field '%s' should not have contained text '%s', but was '%s'", locator, + text, actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Text field '%s' contains text '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textareaShouldContain(String locator, String text) { + textareaShouldContain(locator, text, ""); + } + + /** + * Verify the text area identified by locator contains text.
+ *
+ * Key attributes for text areas are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text area. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textareaShouldNotContain + * @see FormElement#textareaValueShouldBe + * @see FormElement#textareaValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textareaShouldContain(String locator, String text, String message) { + String actual = element.getValue(locator, "text area"); + if (!actual.contains(text)) { + if (message == null) { + message = String.format("Text area '%s' should have contained text '%s', but was '%s'", locator, text, + actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Text field '%s' contains text '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textareaShouldNotContain(String locator, String text) { + textareaShouldNotContain(locator, text, ""); + } + + /** + * Verify the text area identified by locator does not contain text.
+ *
+ * Key attributes for text areas are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text area. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textareaShouldContain + * @see FormElement#textareaValueShouldBe + * @see FormElement#textareaValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textareaShouldNotContain(String locator, String text, String message) { + String actual = element.getValue(locator, "text area"); + if (!actual.contains(text)) { + if (message == null) { + message = String.format("Text area '%s' should not have contained text '%s', but was '%s'", locator, text, + actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Text field '%s' contains text '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textareaValueShouldBe(String locator, String text) { + textareaValueShouldBe(locator, text, ""); + } + + /** + * Verify the text area identified by locator is exactly + * text.
+ *
+ * Key attributes for text area are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text area. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textareaShouldContain + * @see FormElement#textareaShouldNotContain + * @see FormElement#textareaValueShouldNotBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textareaValueShouldBe(String locator, String text, String message) { + String actual = element.getValue(locator, "text area"); + if (!actual.contains(text)) { + if (message == null) { + message = String.format("Value of text area '%s' should have been '%s' but was '%s'", locator, text, + actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Content of text area '%s' is '%s'.", locator, text)); + } + + @RobotKeywordOverload + public void textareaValueShouldNotBe(String locator, String text) { + textareaValueShouldNotBe(locator, text, ""); + } + + /** + * Verify the text area identified by locator is not exactly + * text.
+ *
+ * Key attributes for text area are id and name. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the text area. + * @param text + * The text to verify. + * @param message + * Default=NONE. Optional custom error message. + * + * @see FormElement#textareaShouldContain + * @see FormElement#textareaShouldNotContain + * @see FormElement#textareaValueShouldBe + */ + @RobotKeyword + @ArgumentNames({ "locator", "text", "message=NONE" }) + public void textareaValueShouldNotBe(String locator, String text, String message) { + String actual = element.getValue(locator, "text area"); + if (actual.contains(text)) { + if (message == null) { + message = String.format("Value of text area '%s' should not have been '%s' but was '%s'", locator, + text, actual); + } + throw new Selenium2LibraryNonFatalException(message); + } + logging.info(String.format("Content of text area '%s' is '%s'.", locator, text)); + } + + /** + * Click on the button identified by locator.
+ *
+ * Key attributes for buttons are id, name and value. See `Introduction` for + * details about locators.
+ * + * @param locator + * The locator to locate the link. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void clickButton(String locator) { - info(String.format("Clicking button '%s'.", locator)); - List
+ *
+ * Key attributes for buttons are id, name and value. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the button. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainButton(String locator, String message, String logLevel) { try { - pageShouldContainElement(locator, "input", message, loglevel); - } catch (AssertionError ae) { - pageShouldContainElement(locator, "button", message, loglevel); + element.pageShouldContainElement(locator, "input", message, logLevel); + } catch (Selenium2LibraryNonFatalException e) { + element.pageShouldContainElement(locator, "button", message, logLevel); } } + @RobotKeywordOverload public void pageShouldNotContainButton(String locator) { pageShouldNotContainButton(locator, ""); } + @RobotKeywordOverload public void pageShouldNotContainButton(String locator, String message) { pageShouldNotContainButton(locator, message, "INFO"); } - public void pageShouldNotContainButton(String locator, String message, - String loglevel) { - pageShouldNotContainElement(locator, "input", message, loglevel); - pageShouldNotContainElement(locator, "button", message, loglevel); + /** + * Verify the button identified by locator is not found on the + * current page.
+ *
+ * Key attributes for buttons are id, name and value. See `Introduction` for + * details about log levels and locators.
+ * + * @param locator + * The locator to locate the button. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainButton(String locator, String message, String logLevel) { + element.pageShouldNotContainElement(locator, "input", message, logLevel); + element.pageShouldNotContainElement(locator, "button", message, logLevel); } // ############################## @@ -276,22 +857,20 @@ public void pageShouldNotContainButton(String locator, String message, // ############################## protected WebElement getCheckbox(String locator) { - return elementFind(locator, true, true, "input").get(0); + return element.elementFind(locator, true, true, "input").get(0); } protected List
+ *
+ * If text is a non-empty string, then it is also verified that the + * message of the alert equals to text.
+ *
+ * Will fail if no alert is present. Note that following keywords will fail + * unless the alert is confirmed by this keyword or another like `Confirm + * Action`.
+ * + * @param text + * Default=NONE. The alert message to verify. + */ + @RobotKeyword + @ArgumentNames({ "text=NONE" }) public void alertShouldBePresent(String text) { - String alertText = getAlertMessage(); + String alertText = confirmAction(); if (text != null && !alertText.equals(text)) { - throw new Selenium2LibraryNonFatalException(String.format( - "Alert text should have been '%s' but was '%s'", text, - alertText)); + throw new Selenium2LibraryNonFatalException(String.format("Alert text should have been '%s' but was '%s'", + text, alertText)); } } + /** + * Cancel will be selected the next time a confirmation dialog appears.
+ *
+ * Note that every time a confirmation comes up, it must be confirmed by the + * keywords 'Alert Should Be Present' or `Confirm Action`. Otherwise all + * following operations will fail.
+ */ + @RobotKeyword public void chooseCancelOnNextConfirmation() { - cancelOnNextConfirmation = true; + acceptOnNextConfirmation = false; } + /** + * Ok will be selected the next time a confirmation dialog appears.
+ *
+ * Note that every time a confirmation comes up, it must be confirmed by the + * keywords 'Alert Should Be Present' or `Confirm Action`. Otherwise all + * following operations will fail.
+ */ + @RobotKeyword public void chooseOkOnNextConfirmation() { - cancelOnNextConfirmation = false; + acceptOnNextConfirmation = true; + } + + /** + * Cancel will as default be selected from now on every time a confirmation + * dialog appears.
+ *
+ * Note that every time a confirmation comes up, it must be confirmed by the + * keywords 'Alert Should Be Present' or `Confirm Action`. Otherwise all + * following operations will fail.
+ */ + @RobotKeyword + public void chooseCancelOnConfirmation() { + acceptOnNextConfirmationDefault = false; + acceptOnNextConfirmation = false; } + /** + * Ok will as default be selected from now on every time a confirmation + * dialog appears.
+ *
+ * Note that every time a confirmation comes up, it must be confirmed by the + * keywords 'Alert Should Be Present' or `Confirm Action`. Otherwise all + * following operations will fail.
+ */ + @RobotKeyword + public void chooseOkOnConfirmation() { + acceptOnNextConfirmationDefault = true; + acceptOnNextConfirmation = true; + } + + /** + * Dismisses currently shown confirmation dialog and returns its message.
+ *
+ * By default, this keyword chooses 'OK' option from the dialog. If 'Cancel' + * needs to be chosen, keyword `Choose Cancel On Next Confirmation` must be + * called before the action that causes the confirmation dialog to be shown.
+ *
+ * Example: + *
| Click Button | + *Send | + *+ * | # Shows a confirmation dialog | + *
| ${message}= | + *Confirm Action | + *+ * | # Chooses Ok | + *
| Should Be Equal | + *${message} | + *Are your sure? | + *# Check dialog message | + *
| Choose Cancel On Next Confirmation | + *+ * | + * | # Choose cancel on next `Confirm Action` | + *
| Click Button | + *Send | + *+ * | # Shows a confirmation dialog | + *
| Confirm Action | + *+ * | + * | # Chooses Cancel | + *
+ *
+ * The given code may contain multiple lines of code, but must contain a + * return statement (with the value to be returned) at the end.
+ *
+ * The given code may be divided into multiple cells in the test data. In + * that case, the parts are concatenated together without adding spaces. If + * the given code is an absolute path to an existing file, the JavaScript to + * execute will be read from that file. Forward slashes work as a path + * separator on all operating systems.
+ *
+ * Note that by default the code will be executed in the context of the + * Selenium object itself, so this will refer to the Selenium object. + * Use window to refer to the window of your application, e.g. + * window.document.getElementById('foo').
+ *
+ * Example: + *
| Execute JavaScript | + *return window.my_js_function('arg1', 'arg2'); | + *# Directly execute the JavaScript | + *
| Execute JavaScript | + *${CURDIR}/js_to_execute.js | + *# Load the JavaScript to execute from file | + *
+ *
+ * The given code may contain multiple lines of code, but must contain a + * return statement (with the value to be returned) at the end.
+ *
+ * The given code may be divided into multiple cells in the test data. In + * that case, the parts are concatenated together without adding spaces. If + * the given code is an absolute path to an existing file, the JavaScript to + * execute will be read from that file. Forward slashes work as a path + * separator on all operating systems.
+ *
+ * Note that by default the code will be executed in the context of the + * Selenium object itself, so this will refer to the Selenium object. + * Use window to refer to the window of your application, e.g. + * window.document.getElementById('foo').
+ *
+ * Example: + *
| Execute Async JavaScript | + *return window.my_js_function('arg1', 'arg2'); | + *# Directly execute the JavaScript | + *
| Execute Async JavaScript | + *${CURDIR}/js_to_execute.js | + *# Load the JavaScript to execute from file | + *
+ *
+ * This keyword will fail if no alert is present. Note that following + * keywords will fail unless the alert is confirmed by the keywords 'Alert + * Should Be Present' or `Confirm Action`. + * + * @return The alert message. + */ + @RobotKeyword public String getAlertMessage() { - return closeAlert(); - } - - // ############################## - // Internal Methods - // ############################## - - protected boolean cancelOnNextConfirmation = false; - - protected String closeAlert() { - return closeAlert(false); - } - - protected String closeAlert(boolean confirm) { - Alert alert = null; try { - alert = webDriverCache.getCurrent().switchTo().alert(); + Alert alert = browserManagement.getCurrentWebDriver().switchTo().alert(); String text = alert.getText().replace("\n", ""); - if (!confirm) { - alert.dismiss(); - } else { - alert.accept(); - } return text; } catch (WebDriverException wde) { throw new Selenium2LibraryNonFatalException("There were no alerts"); } } + // ############################## + // Internal Methods + // ############################## + protected static String readFile(String path) throws IOException { FileInputStream stream = new FileInputStream(new File(path)); try { FileChannel fc = stream.getChannel(); - MappedByteBuffer bb = fc.map(FileChannel.MapMode.READ_ONLY, 0, - fc.size()); + MappedByteBuffer bb = fc.map(FileChannel.MapMode.READ_ONLY, 0, fc.size()); /* Instead of using default, pass in a decoder. */ return Charset.defaultCharset().decode(bb).toString(); } finally { @@ -110,14 +316,12 @@ protected String getJavascriptToExecute(String code) { if (!new File(codepath).isFile()) { return code; } - html(String.format( - "Reading JavaScript from file %s.", + logging.html(String.format("Reading JavaScript from file %s.", codepath.replace(File.separatorChar, '/'), codepath)); try { return readFile(codepath); } catch (IOException e) { - throw new Selenium2LibraryNonFatalException( - "Cannot read JavaScript file: " + codepath); + throw new Selenium2LibraryNonFatalException("Cannot read JavaScript file: " + codepath); } } diff --git a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Logging.java b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Logging.java index 5cbf800..399b1d3 100644 --- a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Logging.java +++ b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Logging.java @@ -3,20 +3,26 @@ import java.io.File; import java.io.FileWriter; import java.io.IOException; -import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import org.python.core.PyString; import org.python.util.PythonInterpreter; +import org.robotframework.javalib.annotation.ArgumentNames; +import org.robotframework.javalib.annotation.Autowired; +import org.robotframework.javalib.annotation.RobotKeyword; +import org.robotframework.javalib.annotation.RobotKeywordOverload; +import org.robotframework.javalib.annotation.RobotKeywords; +import com.github.markusbernhardt.selenium2library.RunOnFailureKeywordsAdapter; import com.github.markusbernhardt.selenium2library.Selenium2LibraryNonFatalException; -import com.github.markusbernhardt.selenium2library.utils.Python; -public abstract class Logging extends JavaScript { +@RobotKeywords +public class Logging extends RunOnFailureKeywordsAdapter { protected final static Map
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return List of window id attributes. + * + * @see BrowserManagement#getWindowIdentifiers + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public List
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return List of windows names. + * + * @see BrowserManagement#getWindowNames + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public List
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return List of window titles. + * + * @see BrowserManagement#getWindowTitles + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public List
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return The current location. + * + * @see BrowserManagement#getLocation + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logLocation(String logLevel) { + String actual = browserManagement.getLocation(); + log(actual, logLevel); + return actual; + } + + @RobotKeywordOverload + public String logSource() { + return logSource("INFO"); + } + + /** + * Logs and returns the entire html source of the current page or frame.
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return The entire html source. + * + * @see BrowserManagement#getSource + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logSource(String logLevel) { + String actual = browserManagement.getSource(); + log(actual, logLevel); + return actual; + } + + @RobotKeywordOverload + public String logTitle() { + return logTitle("INFO"); + } + + /** + * Logs and returns the title of current page.
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return The page title. + * + * @see BrowserManagement#getSource + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logTitle(String logLevel) { + String actual = browserManagement.getTitle(); + log(actual, logLevel); + return actual; + } + + @RobotKeywordOverload + public String logSystemInfo() { + return logSystemInfo("INFO"); + } + + /** + * Logs and returns basic system information about the execution + * environment.
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return System information. + * + * @see BrowserManagement#getSystemInfo + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logSystemInfo(String logLevel) { + String actual = browserManagement.getSystemInfo(); + log(actual, logLevel); + return actual; + } + + @RobotKeywordOverload + public String logRemoteCapabilities() { + return logRemoteCapabilities("INFO"); + } + + /** + * Logs and returns the actually supported capabilities of the remote + * browser instance.
+ *
+ * Not all server implementations will support every WebDriver feature. + * Therefore, the client and server should use JSON objects with the + * properties listed below when describing which features a user requests + * that a session support. If a session cannot support a capability that + * is requested in the desired capabilities, no error is thrown; a + * read-only capabilities object is returned that indicates the capabilities + * the session actually supports. For more information see: DesiredCapabilities
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return The capabilities of the remote node. + * + * @see BrowserManagement#getRemoteCapabilities + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logRemoteCapabilities(String logLevel) { + String actual = browserManagement.getRemoteCapabilities(); + log(actual, logLevel); + return actual; + } + + @RobotKeywordOverload + public String logRemoteSessionId() { + return logRemoteSessionId("INFO"); + } + + /** + * Logs and returns the session id of the remote browser instance.
+ *
+ * See `Introduction` for details about the logLevel.
+ * + * @param logLevel + * Default=INFO. Optional log level. + * @return The remote session id. + * + * @see BrowserManagement#getRemoteSessionId + */ + @RobotKeyword + @ArgumentNames({ "logLevel=INFO" }) + public String logRemoteSessionId(String logLevel) { + String actual = browserManagement.getRemoteSessionId(); + log(actual, logLevel); + return actual; + } + + /** + * Set the logDirectory, where captured screenshots are stored, to + * some custom path.
+ *
+ * Fails, if either the given path does not exist, is no directory or is not + * writable.
+ * + * @param logDirectory + * The directory to log to. + */ + @RobotKeyword + @ArgumentNames({ "logDirectory" }) + public void setLogDirectory(String logDirectory) throws Exception { + File file = new File(logDirectory); + + if (file.exists() && file.isDirectory() && file.canWrite()) { + Logging.setLogDir(file.getAbsolutePath()); + } else { + throw new Exception("Location given as parameter: " + logDirectory + + " must exist and must be a writeable directory!"); + } + } + // ############################## // Internal Methods // ############################## - @Override protected void trace(String msg) { log(msg, "trace"); } - @Override protected void debug(String msg) { log(msg, "debug"); } - @Override protected void info(String msg) { log(msg, "info"); } - @Override protected void html(String msg) { log(msg, "html"); } - @Override protected void warn(String msg) { log(msg, "warn"); } - @Override protected void log(String msg, String logLevel) { - String[] methodParameters = VALID_LOG_LEVELS - .get(logLevel.toLowerCase()); + String[] methodParameters = VALID_LOG_LEVELS.get(logLevel.toLowerCase()); if (methodParameters != null) { log0(msg, methodParameters[0], methodParameters[1]); } else { - throw new Selenium2LibraryNonFatalException(String.format( - "Given log level %s is invalid.", logLevel)); + throw new Selenium2LibraryNonFatalException(String.format("Given log level %s is invalid.", logLevel)); } } @@ -74,8 +340,7 @@ protected void log0(String msg, String methodName, String methodArguments) { // There is a hard limit of 100k in the Jython source code parser try { // Write message to temp file - File tempFile = File - .createTempFile("Selenium2Library-", ".log"); + File tempFile = File.createTempFile("Selenium2Library-", ".log"); tempFile.deleteOnExit(); FileWriter writer = new FileWriter(tempFile); writer.write(msg); @@ -83,53 +348,37 @@ protected void log0(String msg, String methodName, String methodArguments) { // Read the message in Python back and log it. loggingPythonInterpreter.get().exec( - String.format("from __future__ import with_statement\n" - + "\n" + "with open('%s', 'r') as msg_file:\n" - + " msg = msg_file.read()\n" - + " logger.%s(msg%s)", tempFile - .getAbsolutePath().replace("\\", "\\\\"), - methodName, methodArguments)); + String.format("from __future__ import with_statement\n" + "\n" + + "with open('%s', 'r') as msg_file:\n" + " msg = msg_file.read()\n" + + " logger.%s(msg%s)", tempFile.getAbsolutePath().replace("\\", "\\\\"), methodName, + methodArguments)); } catch (IOException e) { - throw new Selenium2LibraryNonFatalException( - "Error in handling temp file for long log message.", e); + throw new Selenium2LibraryNonFatalException("Error in handling temp file for long log message.", e); } } else { // Message is small enough to get parsed by Jython loggingPythonInterpreter.get().exec( - String.format("logger.%s('%s'%s)", methodName, - msg.replace("'", "\\'").replace("\n", "\\n"), - methodArguments)); - } - } - - @Override - protected List
+ *
+ * The keyword is the name of a keyword (from any available + * libraries) that will be executed, if a Selenium2Library keyword fails. It + * is not possible to use a keyword that requires arguments. Using the value + * Nothing will disable this feature altogether.
+ *
+ * The initial keyword to use is set at importing the library and the + * keyword that is used by default is `Capture Page Screenshot`. Taking a + * screenshot when something failed is a very useful feature, but notice + * that it can slow down the execution.
+ *
+ * This keyword returns the name of the previously registered failure + * keyword. It can be used to restore the original value later.
+ *
+ * Example: + *
| Register Keyword To Run On Failure | + *Log Source | + *+ * | # Run `Log Source` on failure. | + *
| ${previous kw}= | + *Register Keyword To Run On Failure | + *Nothing | + *# Disable run-on-failure functionality and stors the previous kw name + * in a variable. | + *
| Register Keyword To Run On Failure | + *${previous kw} | + *+ * | # Restore to the previous keyword. | + *
+ *
+ * The filename argument specifies the name of the file to write the + * screenshot into. If no filename is given, the screenshot is saved into + * file selenium-screenshot-<counter>.png under the directory where + * the Robot Framework log file is written into. The filename is also + * considered relative to the same directory, if it is not given in absolute + * format.
+ *
+ * A CSS can be used to modify how the screenshot is taken. By default the + * background color is changed to avoid possible problems with background + * leaking when the page layout is somehow broken.
+ * + * @param filename + * Default=NONE. Name of the file to write. + */ + @RobotKeyword + @ArgumentNames({ "filename=NONE" }) public void capturePageScreenshot(String filename) { - File logdir = getLogDir(); + File logdir = logging.getLogDir(); File path = new File(logdir, normalizeFilename(filename)); String link = Robotframework.getLinkPath(path, logdir); - TakesScreenshot takesScreenshot = ((TakesScreenshot) webDriverCache - .getCurrent()); + TakesScreenshot takesScreenshot = ((TakesScreenshot) browserManagement.getCurrentWebDriver()); if (takesScreenshot == null) { - warn("Can't take screenshot. No open browser found"); + logging.warn("Can't take screenshot. No open browser found"); return; } byte[] png = takesScreenshot.getScreenshotAs(OutputType.BYTES); writeScreenshot(path, png); - html(String - .format("
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @return The select list values + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public List
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @return The first visible select list label + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public String getSelectedListLabel(String locator) { Select select = getSelectList(locator); return select.getFirstSelectedOption().getText(); } + /** + * Returns the visible labels of the first selected elements as a list from + * the select list identified by locator.
+ *
+ * Fails if there is no selection.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @return The list of visible select list labels + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public List
+ *
+ * The return value is read from the value attribute of the selected + * element.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @return The first select list value + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public String getSelectedListValue(String locator) { Select select = getSelectList(locator); return select.getFirstSelectedOption().getAttribute("value"); } + /** + * Returns the values of the first selected elements as a list from the + * select list identified by locator.
+ *
+ * Fails if there is no selection. The return values are read from the value + * attribute of the selected element.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @return The list of select list values + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public List
+ *
+ * If you want to verify no option is selected, simply give no items.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + * @param items + * The list of items to verify + */ + @RobotKeyword + @ArgumentNames({ "locator", "*items" }) public void listSelectionShouldBe(String locator, String... items) { - String itemList = items.length != 0 ? String.format("option(s) [ %s ]", - Python.join(" | ", items)) : "no options"; - info(String.format("Verifying list '%s' has %s selected.", locator, - itemList)); + String itemList = items.length != 0 ? String.format("option(s) [ %s ]", Python.join(" | ", items)) + : "no options"; + logging.info(String.format("Verifying list '%s' has %s selected.", locator, itemList)); - this.pageShouldContainList(locator); + pageShouldContainList(locator); List
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the select list. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void listShouldHaveNoSelections(String locator) { - info(String.format("Verifying list '%s' has no selection.", locator)); + logging.info(String.format("Verifying list '%s' has no selection.", locator)); List
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators and log levels.
+ * + * @param locator + * The locator to locate the select list. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldContainList(String locator, String message, String logLevel) { + element.pageShouldContainElement(locator, "list", message, logLevel); } + @RobotKeywordOverload public void pageShouldNotContainList(String locator) { pageShouldNotContainList(locator, ""); } + @RobotKeywordOverload public void pageShouldNotContainList(String locator, String message) { pageShouldNotContainList(locator, message, "INFO"); } - public void pageShouldNotContainList(String locator, String message, - String logLevel) { - this.pageShouldNotContainElement(locator, "list", message, logLevel); + /** + * Verify the select list identified by locator is not found on the + * current page.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators and log levels.
+ * + * @param locator + * The locator to locate the select list. + * @param message + * Default=NONE. Optional custom error message. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "locator", "message=NONE", "logLevel=INFO" }) + public void pageShouldNotContainList(String locator, String message, String logLevel) { + element.pageShouldNotContainElement(locator, "list", message, logLevel); } + /** + * Select all values of the multi-select list identified by locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + */ + @RobotKeyword + @ArgumentNames({ "locator" }) public void selectAllFromList(String locator) { - info(String.format("Selecting all options from list '%s'.", locator)); + logging.info(String.format("Selecting all options from list '%s'.", locator)); Select select = getSelectList(locator); if (!isMultiselectList(select)) { @@ -142,10 +305,30 @@ public void selectAllFromList(String locator) { } } + /** + * Select the given *items of the multi-select list identified by + * locator.
+ *
+ * An exception is raised for a single-selection list if the last value does + * not exist in the list and a warning for all other non-existing items. For + * a multi-selection list, an exception is raised for any and all + * non-existing values.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param items + * The list of items to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*items" }) public void selectFromList(String locator, String... items) { - String itemList = items.length != 0 ? String.format("option(s) [ %s ]", - Python.join(" | ", items)) : "all options"; - info(String.format("Selecting %s from list '%s'.", itemList, locator)); + String itemList = items.length != 0 ? String.format("option(s) [ %s ]", Python.join(" | ", items)) + : "all options"; + logging.info(String.format("Selecting %s from list '%s'.", itemList, locator)); Select select = getSelectList(locator); @@ -155,21 +338,63 @@ public void selectFromList(String locator, String... items) { for (int i = 0; i < select.getOptions().size(); i++) { select.selectByIndex(i); } + return; } + boolean lastItemFound = false; + List
+ *
+ * Tries to select by value AND by label. It's generally faster to use 'by + * index/value/label' keywords.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param indexes + * The list of indexes to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*indexes" }) public void selectFromListByIndex(String locator, String... indexes) { if (indexes.length == 0) { throw new Selenium2LibraryNonFatalException("No index given."); @@ -180,7 +405,7 @@ public void selectFromListByIndex(String locator, String... indexes) { tmp.add(index); } String items = String.format("index(es) '%s'", Python.join(", ", tmp)); - info(String.format("Selecting %s from list '%s'.", items, locator)); + logging.info(String.format("Selecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); for (String index : indexes) { @@ -188,14 +413,28 @@ public void selectFromListByIndex(String locator, String... indexes) { } } + /** + * Select the given *values of the multi-select list identified by + * locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param values + * The list of values to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*values" }) public void selectFromListByValue(String locator, String... values) { if (values.length == 0) { throw new Selenium2LibraryNonFatalException("No value given."); } - String items = String - .format("value(s) '%s'", Python.join(", ", values)); - info(String.format("Selecting %s from list '%s'.", items, locator)); + String items = String.format("value(s) '%s'", Python.join(", ", values)); + logging.info(String.format("Selecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); for (String value : values) { @@ -203,14 +442,28 @@ public void selectFromListByValue(String locator, String... values) { } } + /** + * Select the given *labels of the multi-select list identified by + * locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param labels + * The list of labels to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*labels" }) public void selectFromListByLabel(String locator, String... labels) { if (labels.length == 0) { throw new Selenium2LibraryNonFatalException("No value given."); } - String items = String - .format("label(s) '%s'", Python.join(", ", labels)); - info(String.format("Selecting %s from list '%s'.", items, locator)); + String items = String.format("label(s) '%s'", Python.join(", ", labels)); + logging.info(String.format("Selecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); for (String label : labels) { @@ -218,10 +471,31 @@ public void selectFromListByLabel(String locator, String... labels) { } } + /** + * Unselect the given *items of the multi-select list identified by + * locator.
+ *
+ * As a special case, giving an empty *items list will remove all + * selections.
+ *
+ * Tries to unselect by value AND by label. It's generally faster to use 'by + * index/value/label' keywords.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param items + * The list of items to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*items" }) public void unselectFromList(String locator, String... items) { - String itemList = items.length != 0 ? String.format("option(s) [ %s ]", - Python.join(" | ", items)) : "all options"; - info(String.format("Unselecting %s from list '%s'.", itemList, locator)); + String itemList = items.length != 0 ? String.format("option(s) [ %s ]", Python.join(" | ", items)) + : "all options"; + logging.info(String.format("Unselecting %s from list '%s'.", itemList, locator)); Select select = getSelectList(locator); @@ -242,6 +516,21 @@ public void unselectFromList(String locator, String... items) { } } + /** + * Unselect the given *indexes of the multi-select list identified by + * locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param indexes + * The list of indexes to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*indexes" }) public void unselectFromListByIndex(String locator, Integer... indexes) { if (indexes.equals(null)) { throw new Selenium2LibraryNonFatalException("No index given."); @@ -252,7 +541,7 @@ public void unselectFromListByIndex(String locator, Integer... indexes) { tmp.add(index.toString()); } String items = String.format("index(es) '%s'", Python.join(", ", tmp)); - info(String.format("Unselecting %s from list '%s'.", items, locator)); + logging.info(String.format("Unselecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); @@ -266,14 +555,28 @@ public void unselectFromListByIndex(String locator, Integer... indexes) { } } + /** + * Unselect the given *values of the multi-select list identified by + * locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param values + * The list of values to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*values" }) public void unselectFromListByValue(String locator, String... values) { if (values.equals(null)) { throw new Selenium2LibraryNonFatalException("No value given."); } - String items = String - .format("value(s) '%s'", Python.join(", ", values)); - info(String.format("Unselecting %s from list '%s'.", items, locator)); + String items = String.format("value(s) '%s'", Python.join(", ", values)); + logging.info(String.format("Unselecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); @@ -287,14 +590,28 @@ public void unselectFromListByValue(String locator, String... values) { } } + /** + * Unselect the given *labels of the multi-select list identified by + * locator.
+ *
+ * Select list keywords work on both lists and combo boxes. Key attributes + * for select lists are id and name. See `Introduction` for details about + * locators.
+ * + * @param locator + * The locator to locate the multi-select list. + * @param labels + * The list of labels to select + */ + @RobotKeyword + @ArgumentNames({ "locator", "*labels" }) public void unselectFromListByLabel(String locator, String... labels) { if (labels.equals(null)) { throw new Selenium2LibraryNonFatalException("No value given."); } - String items = String - .format("label(s) '%s'", Python.join(", ", labels)); - info(String.format("Unselecting %s from list '%s'.", items, locator)); + String items = String.format("label(s) '%s'", Python.join(", ", labels)); + logging.info(String.format("Unselecting %s from list '%s'.", items, locator)); Select select = getSelectList(locator); @@ -312,7 +629,7 @@ public void unselectFromListByLabel(String locator, String... labels) { // Internal Methods // ############################## - private List
+ *
+ * Row and column number start from 1. Header and footer rows are included + * in the count. That way also cell content from header or footer rows can + * be obtained with this keyword.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ * + * @param tableLocator + * The locator to locate the table. + * @param row + * The table row. + * @param column + * The table column. + * @param logLevel + * Default=INFO. Optional log level. + * @return The table cell content. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "row", "column", "logLevel=INFO" }) + public String getTableCell(String tableLocator, int row, int column, String logLevel) { int rowIndex = row - 1; int columnIndex = column - 1; - WebElement table = TableElementFinder.find(webDriverCache.getCurrent(), - tableLocator); + WebElement table = TableElementFinder.find(browserManagement.getCurrentWebDriver(), tableLocator); if (table != null) { List
+ *
+ * Row and column number start from 1. Header and footer rows are included + * in the count. That way also cell content from header or footer rows can + * be obtained with this keyword.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ * + * @param tableLocator + * The locator to locate the table. + * @param row + * The table row. + * @param column + * The table column. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "row", "column", "text", "logLevel=INFO" }) + public void tableCellShouldContain(String tableLocator, int row, int column, String text, String logLevel) { + String message = String.format("Cell in table '%s' in row #%d and column #%d should have contained text '%s'.", + tableLocator, row, column, text); String content = ""; try { - content = getTableCell(tableLocator, row, column, loglevel); - } catch (AssertionError err) { - info(err.getMessage()); + content = getTableCell(tableLocator, row, column, logLevel); + } catch (Selenium2LibraryNonFatalException e) { + logging.info(e.getMessage()); throw new Selenium2LibraryNonFatalException(message); } - info(String.format("Cell contains %s.", content)); - if (!content.contains(expected)) { - logSource(loglevel); + logging.info(String.format("Cell contains %s.", content)); + if (!content.contains(text)) { + logging.logSource(logLevel); throw new Selenium2LibraryNonFatalException(message); } } - public void tableColumnShouldContain(String tableLocator, int col, - String expected) { - tableColumnShouldContain(tableLocator, col, expected, "INFO"); + @RobotKeywordOverload + public void tableColumnShouldContain(String tableLocator, int col, String text) { + tableColumnShouldContain(tableLocator, col, text, "INFO"); } - public void tableColumnShouldContain(String tableLocator, int col, - String expected, String loglevel) { - WebElement element = TableElementFinder.findByCol( - webDriverCache.getCurrent(), tableLocator, col, expected); + /** + * Verify the content of any table cells of the table column of the + * table identified by tableLocator contains text.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ *
+ * The first leftmost column is column number 1. If the table contains cells + * that span multiple columns, those merged cells count as a single column. + * For example both tests below work, if in one row columns A and B are + * merged with colspan="2", and the logical third column contains "C".
+ *
+ * Example: + *
| Table Column Should Contain | + *tableId | + *3 | + *C | + *
| Table Column Should Contain | + *tableId | + *2 | + *C | + *
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ * + * @param tableLocator + * The locator to locate the table. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "text", "logLevel=INFO" }) + public void tableFooterShouldContain(String tableLocator, String text, String logLevel) { + WebElement element = TableElementFinder.findByFooter(browserManagement.getCurrentWebDriver(), tableLocator, + text); if (element == null) { - logSource(loglevel); - throw new Selenium2LibraryNonFatalException( - String.format( - "Footer in table identified by '%s' should have contained text '%s'.", - tableLocator, expected)); + logging.logSource(logLevel); + throw new Selenium2LibraryNonFatalException(String.format( + "Footer in table identified by '%s' should have contained text '%s'.", tableLocator, text)); } } - public void tableHeaderShouldContain(String tableLocator, String expected) { - tableHeaderShouldContain(tableLocator, expected, "INFO"); + @RobotKeywordOverload + public void tableHeaderShouldContain(String tableLocator, String text) { + tableHeaderShouldContain(tableLocator, text, "INFO"); } - public void tableHeaderShouldContain(String tableLocator, String expected, - String loglevel) { - WebElement element = TableElementFinder.findByHeader( - webDriverCache.getCurrent(), tableLocator, expected); + /** + * Verify the content of any table header cells of the table identified by + * tableLocator contains text.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ * + * @param tableLocator + * The locator to locate the table. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "text", "logLevel=INFO" }) + public void tableHeaderShouldContain(String tableLocator, String text, String logLevel) { + WebElement element = TableElementFinder.findByHeader(browserManagement.getCurrentWebDriver(), tableLocator, + text); if (element == null) { - logSource(loglevel); - throw new Selenium2LibraryNonFatalException( - String.format( - "Header in table identified by '%s' should have contained text '%s'.", - tableLocator, expected)); + logging.logSource(logLevel); + throw new Selenium2LibraryNonFatalException(String.format( + "Header in table identified by '%s' should have contained text '%s'.", tableLocator, text)); } } - public void tableRowShouldContain(String tableLocator, int row, - String expected) { - tableRowShouldContain(tableLocator, row, expected, "INFO"); + @RobotKeywordOverload + public void tableRowShouldContain(String tableLocator, int row, String text) { + tableRowShouldContain(tableLocator, row, text, "INFO"); } - public void tableRowShouldContain(String tableLocator, int row, - String expected, String loglevel) { - WebElement element = TableElementFinder.findByRow( - webDriverCache.getCurrent(), tableLocator, row, expected); + /** + * Verify the content of any table cells of the table row of the + * table identified by tableLocator contains text.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ *
+ * The uppermost row is row number 1. For tables that are structured with + * thead, tbody and tfoot, only the tbody section is searched. Please use + * Table Header Should Contain or Table Footer Should Contain for tests + * against the header or footer content.
+ *
+ * If the table contains cells that span multiple rows, a match only occurs + * for the uppermost row of those merged cells.
+ * + * @param tableLocator + * The locator to locate the table. + * @param row + * The table row. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "row", "text", "logLevel=INFO" }) + public void tableRowShouldContain(String tableLocator, int row, String text, String logLevel) { + WebElement element = TableElementFinder.findByRow(browserManagement.getCurrentWebDriver(), tableLocator, row, + text); if (element == null) { - logSource(loglevel); - throw new Selenium2LibraryNonFatalException( - String.format( - "Row #%d in table identified by '%s' should have contained text '%s'.", - row, tableLocator, expected)); + logging.logSource(logLevel); + throw new Selenium2LibraryNonFatalException(String.format( + "Row #%d in table identified by '%s' should have contained text '%s'.", row, tableLocator, text)); } } - public void tableShouldContain(String tableLocator, String expected) { - tableShouldContain(tableLocator, expected, "INFO"); + @RobotKeywordOverload + public void tableShouldContain(String tableLocator, String text) { + tableShouldContain(tableLocator, text, "INFO"); } - public void tableShouldContain(String tableLocator, String expected, - String loglevel) { - WebElement element = TableElementFinder.findByContent( - webDriverCache.getCurrent(), tableLocator, expected); + /** + * Verify the content of any table cells of the table identified by + * tableLocator contains text.
+ *
+ * Key attributes for tables are id and name. See `Introduction` for details + * about locators and log levels.
+ * + * @param tableLocator + * The locator to locate the table. + * @param text + * The text to verify. + * @param logLevel + * Default=INFO. Optional log level. + */ + @RobotKeyword + @ArgumentNames({ "tableLocator", "text", "logLevel=INFO" }) + public void tableShouldContain(String tableLocator, String text, String logLevel) { + WebElement element = TableElementFinder.findByContent(browserManagement.getCurrentWebDriver(), tableLocator, + text); if (element == null) { - logSource(loglevel); - throw new Selenium2LibraryNonFatalException( - String.format( - "Table identified by '%s' should have contained text '%s'.", - tableLocator, expected)); + logging.logSource(logLevel); + throw new Selenium2LibraryNonFatalException(String.format( + "Table identified by '%s' should have contained text '%s'.", tableLocator, text)); } } diff --git a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Waiting.java b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Waiting.java index fe64f51..411b95a 100644 --- a/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Waiting.java +++ b/src/main/java/com/github/markusbernhardt/selenium2library/keywords/Waiting.java @@ -1,83 +1,669 @@ package com.github.markusbernhardt.selenium2library.keywords; import org.openqa.selenium.JavascriptExecutor; +import org.robotframework.javalib.annotation.ArgumentNames; +import org.robotframework.javalib.annotation.Autowired; +import org.robotframework.javalib.annotation.RobotKeyword; +import org.robotframework.javalib.annotation.RobotKeywordOverload; +import org.robotframework.javalib.annotation.RobotKeywords; +import com.github.markusbernhardt.selenium2library.RunOnFailureKeywordsAdapter; import com.github.markusbernhardt.selenium2library.Selenium2LibraryNonFatalException; import com.github.markusbernhardt.selenium2library.utils.Robotframework; -public abstract class Waiting extends TableElement { +@RobotKeywords +public class Waiting extends RunOnFailureKeywordsAdapter { + + /** + * Instantiated BrowserManagement keyword bean + */ + @Autowired + protected BrowserManagement browserManagement; + + /** + * Instantiated Element keyword bean + */ + @Autowired + protected Element element; // ############################## // Keywords // ############################## + @RobotKeywordOverload public void waitForCondition(String condition) { waitForCondition(condition, null); } - public void waitForCondition(String condition, String timestr) { - waitForCondition(condition, timestr, null); + @RobotKeywordOverload + public void waitForCondition(String condition, String timeout) { + waitForCondition(condition, timeout, null); } - public void waitForCondition(final String condition, String timestr, - String error) { - if (error == null) { - error = String.format( - "Condition '%s' did not become true in
+ *
+ * Fails, if the timeout expires, before the condition gets true.
+ *
+ * The condition may contain multiple JavaScript statements, but the last + * statement must return a boolean. Otherwise this keyword will always hit + * the timeout.
+ *
+ * Note that by default the code will be executed in the context of the + * Selenium object itself, so this will refer to the Selenium object. + * Use window to refer to the window of your application, e.g. + * window.document.getElementById('foo').
+ *
+ * See `Introduction` for details about timeouts.
+ * + * @param condition + * The JavaScript condition returning a boolean. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "condition", "timeout=NONE", "message=NONE" }) + public void waitForCondition(final String condition, String timeout, String message) { + if (message == null) { + message = String.format("Condition '%s' did not become true in
+ *
+ * Fails, if the timeout expires, before the text appears.
+ *
+ * See `Introduction` for details about timeouts.
+ * + * @param text + * The text to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "condition", "timeout=NONE", "message=NONE" }) + public void waitUntilPageContains(final String text, String timeout, String message) { + if (message == null) { + message = String.format("Text '%s' did not appear in
+ *
+ * Fails, if the timeout expires, before the text disappears.
+ *
+ * See `Introduction` for details about timeouts.
+ * + * @param text + * The text to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "text", "timeout=NONE", "message=NONE" }) + public void waitUntilPageNotContains(final String text, String timeout, String message) { + if (message == null) { + message = String.format("Text '%s' did not disappear in
+ *
+ * Fails, if the timeout expires, before the element appears.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilPageContainsElement(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' did not appear in
+ *
+ * Fails, if the timeout expires, before the element disappears.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilPageNotContainsElement(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' did not disappear in
+ *
+ * Fails, if the timeout expires, before the element gets visible.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsVisible(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' not visible in
+ *
+ * Fails, if the timeout expires, before the element gets invisible.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsNotVisible(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' still visible in
+ *
+ * Fails, if the timeout expires, before the element gets clickable.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsClickable(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' not clickable in
+ *
+ * Fails, if the timeout expires, before the element gets unclickable.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsNotClickable(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' still clickable in
+ *
+ * Fails, if the timeout expires, before the element gets clicked on.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsSuccessfullyClicked(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' not successfully clicked in
+ *
+ * Fails, if the timeout expires, before the element gets selected.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsSelected(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' not selected in
+ *
+ * Fails, if the timeout expires, before the element gets unselected.
+ *
+ * See `Introduction` for details about locators and timeouts.
+ * + * @param locator + * The locator to locate the element. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "locator", "timeout=NONE", "message=NONE" }) + public void waitUntilElementIsNotSelected(final String locator, String timeout, String message) { + if (message == null) { + message = String.format("Element '%s' still selected in
+ *
+ * Fails, if the timeout expires, before the page title contains the given + * title.
+ * + * @param title + * The title to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "title", "timeout=NONE", "message=NONE" }) + public void waitUntilTitleContains(final String title, String timeout, String message) { + if (message == null) { + message = String.format("Title '%s' did not appear in
+ *
+ * Fails, if the timeout expires, before the page title does not contain the + * given title.
+ * + * @param title + * The title to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "title", "timeout=NONE", "message=NONE" }) + public void waitUntilTitleNotContains(final String title, String timeout, String message) { + if (message == null) { + message = String.format("Title '%s' did not appear in
+ *
+ * Fails, if the timeout expires, before the page title matches the given + * title.
+ * + * @param title + * The title to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "title", "timeout=NONE", "message=NONE" }) + public void waitUntilTitleIs(final String title, String timeout, String message) { + if (message == null) { + message = String.format("Title '%s' did not appear in
+ *
+ * Fails, if the timeout expires, before the page title does not match the + * given title.
+ * + * @param title + * The title to verify. + * @param timeout + * Default=NONE. Optional timeout interval. + * @param message + * Default=NONE. Optional custom error message. + */ + @RobotKeyword + @ArgumentNames({ "title", "timeout=NONE", "message=NONE" }) + public void waitUntilTitleIsNot(final String title, String timeout, String message) { + if (message == null) { + message = String.format("Title '%s' did not appear in