diff --git a/.gitignore b/.gitignore index 66768f8..8262605 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,10 @@ -<<<<<<< HEAD -======= *.html *.xml pabot_results/ .DS_Store .pabotsuitenames ->>>>>>> 3cc58ce6db279811ff4b164f3dc5afca4d15c153 +*.jpg +*.project +*.png +libspecs/ +.DS_Store \ No newline at end of file diff --git a/Jenkinsfile b/Jenkinsfile index 7659e6a..2cee130 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -3,7 +3,7 @@ node { stage('Preparation') { // for display purposes //pass login properties([parameters([credentials(credentialType: 'com.browserstack.automate.ci.jenkins.BrowserStackCredentials', defaultValue: '', description: '', name: 'BROWSERSTACK_USERNAME', required: true), choice(choices: ['single', 'local', 'parallel - testsuite level', 'parallel - testcase level', 'appium_android', 'appium_ios', 'appium parallel'], description: 'Included Automate and App-Automate tests', name: 'Command')])]) - git changelog: false, poll: false, url: 'https://github.com/nithyamn/bs-robot-framework.git' + git changelog: false, poll: false, url: 'https://github.com/BrowserStackCE/bstack-robot-framework.git' } stage('Initiate tests on BrowserStack') { browserstack(credentialsId: "${params.BROWSERSTACK_USERNAME}",localConfig: [localOptions: '', localPath: '']) { diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f9c7afb --- /dev/null +++ b/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright (c) 2021, BrowserStack Limited. https://www.browserstack.com + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/app/test/Appium_android.robot b/app/test/Appium_android.robot index dcfcd9a..3f65fb8 100644 --- a/app/test/Appium_android.robot +++ b/app/test/Appium_android.robot @@ -5,7 +5,7 @@ Library Process *** Variables *** ${USERNAME} %{BROWSERSTACK_USERNAME} #Can specify BrowserStack Username directly instead of Environment variable. ${ACCESS_KEY} %{BROWSERSTACK_ACCESS_KEY} #Can specify BrowserStack Accesskey directly instead of Environment variable. -${REMOTE_URL} http://${USERNAME}:${ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub +${REMOTE_URL} http://${USERNAME}:${ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub *** Test Cases *** Appium Test on BrowserStack @@ -21,6 +21,7 @@ Appium Test on BrowserStack Close Application + # Upload app programatically # ${AppUrl} Run Process curl -u "${USERNAME}:${ACCESS_KEY}" -X POST "https://api-cloud.browserstack.com/app-automate/upload" -F "file\=@${APP_PATH}" shell=true alias=AppUpload # ${AppData} Evaluate json.loads("""${AppUrl.stdout}""") json # Log ${AppUrl.stdout} diff --git a/app/test/Appium_ios.robot b/app/test/Appium_ios.robot index be5699c..1fbe347 100644 --- a/app/test/Appium_ios.robot +++ b/app/test/Appium_ios.robot @@ -16,6 +16,8 @@ Appium Test on BrowserStack Click Element accessibility_id=OK Close Application + + # Upload app programatically # ${AppUrl} Run Process curl -u "${USERNAME}:${ACCESS_KEY}" -X POST "https://api-cloud.browserstack.com/app-automate/upload" -F "file\=@${APP_PATH}" shell=true alias=AppUpload # ${AppData} Evaluate json.loads("""${AppUrl.stdout}""") json # Log ${AppUrl.stdout} diff --git a/app/test/appium-screenshot-1.png b/app/test/appium-screenshot-1.png deleted file mode 100644 index 3346af9..0000000 Binary files a/app/test/appium-screenshot-1.png and /dev/null differ diff --git a/app/test/parallel/Suite1_App.robot b/app/test/parallel/Suite1_App.robot index 043cd6b..46fb21e 100644 --- a/app/test/parallel/Suite1_App.robot +++ b/app/test/parallel/Suite1_App.robot @@ -6,7 +6,6 @@ Library Process ${USERNAME} %{BROWSERSTACK_USERNAME} #Can specify BrowserStack Username directly instead of Environment variable. ${ACCESS_KEY} %{BROWSERSTACK_ACCESS_KEY} #Can specify BrowserStack Accesskey directly instead of Environment variable. ${REMOTE_URL} http://${USERNAME}:${ACCESS_KEY}@hub-cloud.browserstack.com/wd/hub -${APP_PATH} /Users/nithyamani/Desktop/APPS/WikipediaSample.apk *** Test Cases *** Appium Test on BrowserStack diff --git a/libspecs/AppiumLibrary_44335e8.libspec b/libspecs/AppiumLibrary_44335e8.libspec deleted file mode 100644 index 86e352c..0000000 --- a/libspecs/AppiumLibrary_44335e8.libspec +++ /dev/null @@ -1,1369 +0,0 @@ - - -1.5.0.4 -global -yes -AppiumLibrary is a Mobile App testing library for Robot Framework. - -= Locating or specifying elements = - -All keywords in AppiumLibrary that need to find an element on the page -take an argument, either a ``locator`` or a ``webelement``. ``locator`` -is a string that describes how to locate an element using a syntax -specifying different location strategies. ``webelement`` is a variable that -holds a WebElement instance, which is a representation of the element. - -== Using locators == - -By default, when a locator is provided, it is matched against the key attributes -of the particular element type. For iOS and Android, key attribute is ``id`` for -all elements and locating elements is easy using just the ``id``. For example: - -| Click Element id=my_element - -New in AppiumLibrary 1.4, ``id`` and ``xpath`` are not required to be specified, -however ``xpath`` should start with ``//`` else just use ``xpath`` locator as explained below. - -For example: - -| Click Element my_element -| Wait Until Page Contains Element //*[@type="android.widget.EditText"] - - -Appium additionally supports some of the [https://w3c.github.io/webdriver/webdriver-spec.html|Mobile JSON Wire Protocol] locator strategies. -It is also possible to specify the approach AppiumLibrary should take -to find an element by specifying a lookup strategy with a locator -prefix. Supported strategies are: - -| *Strategy* | *Example* | *Description* | *Note* | -| identifier | Click Element `|` identifier=my_element | Matches by @id attribute | | -| id | Click Element `|` id=my_element | Matches by @resource-id attribute | | -| accessibility_id | Click Element `|` accessibility_id=button3 | Accessibility options utilize. | | -| xpath | Click Element `|` xpath=//UIATableView/UIATableCell/UIAButton | Matches with arbitrary XPath | | -| class | Click Element `|` class=UIAPickerWheel | Matches by class | | -| android | Click Element `|` android=UiSelector().description('Apps') | Matches by Android UI Automator | | -| ios | Click Element `|` ios=.buttons().withName('Apps') | Matches by iOS UI Automation | | -| nsp | Click Element `|` nsp=name=="login" | Matches by iOSNsPredicate | Check PR: #196 | -| css | Click Element `|` css=.green_button | Matches by css in webview | | -| name | Click Element `|` name=my_element | Matches by @name attribute | *Only valid* for Selendroid | - -== Using webelements == - -Starting with version 1.4 of the AppiumLibrary, one can pass an argument -that contains a WebElement instead of a string locator. To get a WebElement, -use the new `Get WebElements` or `Get WebElement` keyword. - -For example: -| @{elements} Get Webelements class=UIAButton -| Click Element @{elements}[2] - - -timeout=5 -run_on_failure=Capture Page Screenshot - -AppiumLibrary can be imported with optional arguments. - -``timeout`` is the default timeout used to wait for all waiting actions. -It can be later set with `Set Appium Timeout`. - -``run_on_failure`` specifies the name of a keyword (from any available -libraries) to execute when a AppiumLibrary keyword fails. - -By default `Capture Page Screenshot` will be used to take a screenshot of the current page. -Using the value `No Operation` will disable this feature altogether. See -`Register Keyword To Run On Failure` keyword for more information about this -functionality. - -Examples: -| Library | AppiumLibrary | 10 | # Sets default timeout to 10 seconds | -| Library | AppiumLibrary | timeout=10 | run_on_failure=No Operation | # Sets default timeout to 10 seconds and does nothing on failure | - - - - - -seconds=5 - -Puts the application in the background on the device for a certain -duration. - - - - - -filename=None - -Takes a screenshot of the current page and embeds it into the log. - -`filename` argument specifies the name of the file to write the -screenshot into. If no `filename` is given, the screenshot is saved into file -`appium-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. - -`css` can be used to modify how the screenshot is taken. By default -the bakground color is changed to avoid possible problems with -background leaking when the page layout is somehow broken. - - - - - -locator - -Clears the text field identified by `locator`. - -See `introduction` for details about locating elements. - - - - - -x=0 -y=0 -duration=100 - -Click on a point - - - - - -index_or_name - -Click button - - - - - -locator - -Click element identified by `locator`. - -Key attributes for arbitrary elements are `index` and `name`. See -`introduction` for details about locating elements. - - - - - -coordinate_X -coordinate_Y - -click element at a certain coordinate - - - - - -text -exact_match=False - -Click text identified by ``text``. - -By default tries to click first text involves given ``text``, if you would -like to click exactly matching text, then set ``exact_match`` to `True`. - -If there are multiple use of ``text`` and you do not want first one, -use `locator` with `Get Web Elements` instead. - - - - - - -Closes all open applications. - -This keyword is meant to be used in test or suite teardown to -make sure all the applications are closed before the test execution -finishes. - -After this keyword, the application indices returned by `Open Application` -are reset and start from `1`. - - - - - - -Closes the current application and also close webdriver session. - - - - - -locator -attr_name -match_pattern -regexp=False - -Verify that an attribute of an element matches the expected criteria. - -The element is identified by _locator_. See `introduction` for details -about locating elements. If more than one element matches, the first element is selected. - -The _attr_name_ is the name of the attribute within the selected element. - -The _match_pattern_ is used for the matching, if the match_pattern is -- boolean or 'True'/'true'/'False'/'false' String then a boolean match is applied -- any other string is cause a string match - -The _regexp_ defines whether the string match is done using regular expressions (i.e. BuiltIn Library's -[http://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Should%20Match%20Regexp|Should -Match Regexp] or string pattern match (i.e. BuiltIn Library's -[http://robotframework.org/robotframework/latest/libraries/BuiltIn.html#Should%20Match|Should -Match]) - - -Examples: - -| Element Attribute Should Match | xpath = //*[contains(@text,'foo')] | text | *foobar | -| Element Attribute Should Match | xpath = //*[contains(@text,'foo')] | text | f.*ar | regexp = True | -| Element Attribute Should Match | xpath = //*[contains(@text,'foo')] | enabled | True | - -| 1. is a string pattern match i.e. the 'text' attribute should end with the string 'foobar' -| 2. is a regular expression match i.e. the regexp 'f.*ar' should be within the 'text' attribute -| 3. is a boolead match i.e. the 'enabled' attribute should be True - - -_*NOTE: *_ -On Android the supported attribute names are hard-coded in the -[https://github.com/appium/appium/blob/master/lib/devices/android/bootstrap/src/io/appium/android/bootstrap/AndroidElement.java|AndroidElement] -Class's getBoolAttribute() and getStringAttribute() methods. -Currently supported (appium v1.4.11): -_contentDescription, text, className, resourceId, enabled, checkable, checked, clickable, focusable, focused, longClickable, scrollable, selected, displayed_ - - -_*NOTE: *_ -Some attributes can be evaluated in two different ways e.g. these evaluate the same thing: - -| Element Attribute Should Match | xpath = //*[contains(@text,'example text')] | name | txt_field_name | -| Element Name Should Be | xpath = //*[contains(@text,'example text')] | txt_field_name | | - - - - - -locator -expected - - - - - - - -locator -loglevel=INFO - -Verifies that element identified with locator is disabled. - -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - - - - - -locator -loglevel=INFO - -Verifies that element identified with locator is enabled. - -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - - - - - -locator -loglevel=INFO - -Verifies that element identified with locator is visible. - -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - -New in AppiumLibrary 1.4.5 - - - - - -locator -expected -message= - -Verifies element identified by ``locator`` contains text ``expected``. - -If you wish to assert an exact (not a substring) match on the text -of the element, use `Element Text Should Be`. - -Key attributes for arbitrary elements are ``id`` and ``xpath``. ``message`` can be used to override the default error message. - -New in AppiumLibrary 1.4. - - - - - -locator -expected -message= - -Verifies element identified by ``locator`` does not contain text ``expected``. - -``message`` can be used to override the default error message. -See `Element Should Contain Text` for more details. - - - - - -locator -expected -message= - -Verifies element identified by ``locator`` exactly contains text ``expected``. - -In contrast to `Element Should Contain Text`, this keyword does not try -a substring match but an exact match on the element identified by ``locator``. - -``message`` can be used to override the default error message. - -New in AppiumLibrary 1.4. - - - - - -locator -expected - - - - - - - -command -*args - -Execute ADB shell commands - -Android only. - -- _command_ - The ABD shell command -- _args_ - Arguments to send to command - -Returns the exit code of ADB shell. - -Requires server flag --relaxed-security to be set on Appium server. - - - - - -script - -Inject a snippet of Async-JavaScript into the page for execution in the -context of the currently selected frame (Web context only). - -The executed script is assumed to be asynchronous and must signal that is done by -invoking the provided callback, which is always provided as the final argument to the -function. - -The value to this callback will be returned to the client. - - -New in AppiumLibrary 1.5 - - - - - -script - -Inject a snippet of JavaScript into the page for execution in the -context of the currently selected frame (Web context only). - -The executed script is assumed to be synchronous and the result -of evaluating the script is returned to the client. - -New in AppiumLibrary 1.5 - - - - - - -Retrieves the current activity on the device. - -Android only. - - - - - - -Returns the current session ID as a reference - - - - - - -Gets the timeout in seconds that is used by various keywords. - -See `Set Appium Timeout` for an explanation. - - - - - -capability_name - -Return the desired capability value by desired capability name - - - - - - -Get available contexts. - - - - - - -Get current context. - - - - - -locator -attribute - -Get element attribute using given attribute: name, value,... - -Examples: - -| Get Element Attribute | locator | name | -| Get Element Attribute | locator | value | - - - - - -locator - -Get element location - -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - - - - - -locator - -Get element size - -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - - - - - -xpath - -Returns number of elements matching ``xpath`` - -One should not use the `xpath=` prefix for 'xpath'. XPath is assumed. - -| *Correct:* | -| ${count} | Get Matching Xpath Count | //android.view.View[@text='Test'] | -| Incorrect: | -| ${count} | Get Matching Xpath Count | xpath=//android.view.View[@text='Test'] | - -If you wish to assert the number of matching elements, use -`Xpath Should Match X Times`. - -New in AppiumLibrary 1.4. - - - - - - -Returns an integer bitmask specifying the network connection type. - -Android only. - -See `set network connection status` for more details. - - - - - - -Returns the entire source of the current page. - - - - - -locator - -Get element text (for hybrid and mobile browser use `xpath` locator, others might cause problem) - -Example: - -| ${text} | Get Text | //*[contains(@text,'foo')] | - -New in AppiumLibrary 1.4. - - - - - -locator - -Returns the first [http://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement|WebElement] object matching ``locator``. - -Example: -| ${element} | Get Webelement | id=my_element | -| Click Element | ${element} | | - -New in AppiumLibrary 1.4. - - - - - -locator - -Returns list of [http://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement|WebElement] objects matching ``locator``. - -Example: -| @{elements} | Get Webelements | id=my_element | -| Click Element | @{elements}[2] | | - -This keyword was changed in AppiumLibrary 1.4 in following ways: -- Name is changed from `Get Elements` to current one. -- Deprecated argument ``fail_on_error``, use `Run Keyword and Ignore Error` if necessary. - -New in AppiumLibrary 1.4. - - - - - - -Get current device height. - -Example: -| ${width} | Get Window Height | -| ${height} | Get Window Height | -| Click A Point | ${width | ${height} | - -New in AppiumLibrary 1.4.5 - - - - - - -Get current device width. - -Example: -| ${width} | Get Window Height | -| ${height} | Get Window Height | -| Click A Point | ${width | ${height} | - -New in AppiumLibrary 1.4.5 - - - - - - -Goes one step backward in the browser history. - - - - - -url - -Opens URL in default web browser. - -Example: -| Open Application | http://localhost:4755/wd/hub | platformName=iOS | platformVersion=7.0 | deviceName='iPhone Simulator' | browserName=Safari | -| Go To URL | http://m.webapp.com | - - - - - -key_name=None - -Hides the software keyboard on the device. (optional) In iOS, use `key_name` to press -a particular key, ex. `Done`. In Android, no parameters are used. - - - - - -locator -text - -Types the given password into text field identified by `locator`. - -Difference between this keyword and `Input Text` is that this keyword -does not log the given password. See `introduction` for details about -locating elements. - - - - - -locator -text - -Types the given `text` into text field identified by `locator`. - -See `introduction` for details about locating elements. - - - - - -locator -text - -Sets the given value into text field identified by `locator`. This is an IOS only keyword, input value makes use of set_value - -See `introduction` for details about locating elements. - - - - - -app_path -app_package - -Install App via Appium - -Android only. - -- app_path - path to app -- app_package - package of install app to verify - - - - - - -Set the device orientation to LANDSCAPE - - - - - - -Launch application. Application can be launched while Appium session running. -This keyword can be used to launch application during test case or between test cases. - -This keyword works while `Open Application` has a test running. This is good practice to `Launch Application` -and `Quit Application` between test cases. As Suite Setup is `Open Application`, `Test Setup` can be used to `Launch Application` - -Example (syntax is just a representation, refer to RF Guide for usage of Setup/Teardown): -| [Setup Suite] | -| | Open Application | http://localhost:4723/wd/hub | platformName=Android | deviceName=192.168.56.101:5555 | app=${CURDIR}/demoapp/OrangeDemoApp.apk | -| [Test Setup] | -| | Launch Application | -| | | <<<test execution>>> | -| | | <<<test execution>>> | -| [Test Teardown] | -| | Quit Application | -| [Suite Teardown] | -| | Close Application | - -See `Quit Application` for quiting application but keeping Appium sesion running. - -New in AppiumLibrary 1.4.6 - - - - - -seconds=5 - -Lock the device for a certain period of time. iOS only. - - - - - -loglevel=INFO - -Logs and returns the entire html source of the current page or frame. - -The `loglevel` argument defines the used log level. Valid log levels are -`WARN`, `INFO` (default), `DEBUG`, `TRACE` and `NONE` (no logging). - - - - - -locator -duration=1000 - -Long press the element with optional duration - - - - - -keycode -metastate=None - -Sends a long press of keycode to the device. - -Android only. - -See `press keycode` for more details. - - - - - -remote_url -alias=None -**kwargs - -Opens a new application to given Appium server. -Capabilities of appium server, Android and iOS, -Please check https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/server-args.md -| *Option* | *Man.* | *Description* | -| remote_url | Yes | Appium server url | -| alias | no | alias | - -Examples: -| Open Application | http://localhost:4723/wd/hub | alias=Myapp1 | platformName=iOS | platformVersion=7.0 | deviceName='iPhone Simulator' | app=your.app | -| Open Application | http://localhost:4723/wd/hub | platformName=Android | platformVersion=4.2.2 | deviceName=192.168.56.101:5555 | app=${CURDIR}/demoapp/OrangeDemoApp.apk | appPackage=com.netease.qa.orangedemo | appActivity=MainActivity | - - - - - -locator -loglevel=INFO - -Verifies that current page contains `locator` element. - -If this keyword fails, it automatically logs the page source -using the log level specified with the optional `loglevel` argument. -Giving `NONE` as level disables logging. - - - - - -text -loglevel=INFO - -Verifies that current page contains `text`. - -If this keyword fails, it automatically logs the page source -using the log level specified with the optional `loglevel` argument. -Giving `NONE` as level disables logging. - - - - - -locator -loglevel=INFO - -Verifies that current page not contains `locator` element. - -If this keyword fails, it automatically logs the page source -using the log level specified with the optional `loglevel` argument. -Giving `NONE` as level disables logging. - - - - - -text -loglevel=INFO - -Verifies that current page not contains `text`. - -If this keyword fails, it automatically logs the page source -using the log level specified with the optional `loglevel` argument. -Giving `NONE` as level disables logging. - - - - - -locator -percent=200% -steps=1 - -Pinch in on an element a certain amount. - - - - - - -Set the device orientation to PORTRAIT - - - - - -keycode -metastate=None - -Sends a press of keycode to the device. - -Android only. - -Possible keycodes & meta states can be found in -http://developer.android.com/reference/android/view/KeyEvent.html - -Meta state describe the pressed state of key modifiers such as -Shift, Ctrl & Alt keys. The Meta State is an integer in which each -bit set to 1 represents a pressed meta key. - -For example -- META_SHIFT_ON = 1 -- META_ALT_ON = 2 - -| metastate=1 --> Shift is pressed -| metastate=2 --> Alt is pressed -| metastate=3 --> Shift+Alt is pressed - - - _keycode- - the keycode to be sent to the device - - _metastate- - status of the meta keys - - - - - -path -decode=False - -Retrieves the file at `path` and return it's content. - -Android only. - - - _path_ - the path to the file on the device - - _decode_ - True/False decode the data (base64) before returning it (default=False) - - - - - -path -decode=False - -Retrieves a folder at `path`. Returns the folder's contents zipped. - -Android only. - - - _path_ - the path to the folder on the device - - _decode_ - True/False decode the data (base64) before returning it (default=False) - - - - - -path -data -encode=False - -Puts the data in the file specified as `path`. - -Android only. - - - _path_ - the path on the device - - _data_ - data to be written to the file - - _encode_ - True/False encode the data as base64 before writing it to the file (default=False) - - - - - - -Quit application. Application can be quit while Appium session is kept alive. -This keyword can be used to close application during test case or between test cases. - -See `Launch Application` for an explanation. - -New in AppiumLibrary 1.4.6 - - - - - -keyword - -Sets the keyword to execute when a AppiumLibrary keyword fails. - -`keyword_name` is the name of a keyword (from any available -libraries) that will be executed if a AppiumLibrary 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 in `importing`, 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 | # Disables run-on-failure functionality and stores the previous kw name in a variable. | -| Register Keyword To Run On Failure | ${previous kw} | # Restore to the previous keyword. | - -This run-on-failure functionality only works when running tests on Python/Jython 2.4 -or newer and it does not work on IronPython at all. - - - - - -application_id - -Removes the application that is identified with an application id - -Example: -| Remove Application | com.netease.qa.orangedemo | - - - - - - -Reset application. Open Application can be reset while Appium session is kept alive. - - - - - -start_locator -end_locator - -Scrolls from one element to another -Key attributes for arbitrary elements are `id` and `name`. See -`introduction` for details about locating elements. - - - - - -locator - -Scrolls down to element - - - - - -locator - -Scrolls up to element - - - - - -seconds - -Sets the timeout in seconds used by various keywords. - -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 this keyword. - -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`. - -Example: -| ${orig timeout} = | Set Appium Timeout | 15 seconds | -| Open page that loads slowly | -| Set Appium Timeout | ${orig timeout} | - - - - - -latitude -longitude -altitude=10 - -Set location - -- _latitute_ -- _longitude_ -- _altitude_ = 10 [optional] - -Android only. -New in AppiumLibrary 1.5 - - - - - -connectionStatus - -Sets the network connection Status. - -Android only. - -Possible values: - | =Value= | =Alias= | =Data= | =Wifi= | =Airplane Mode= | - | 0 | (None) | 0 | 0 | 0 | - | 1 | (Airplane Mode) | 0 | 0 | 1 | - | 2 | (Wifi only) | 0 | 1 | 0 | - | 4 | (Data only) | 1 | 0 | 0 | - | 6 | (All network on) | 1 | 1 | 0 | - - - - - - -Shake the device - - - - - -appPackage -appActivity -**opts - -Opens an arbitrary activity during a test. If the activity belongs to -another application, that application is started and the activity is opened. - -Android only. - -- _appPackage_ - The package containing the activity to start. -- _appActivity_ - The activity to start. -- _appWaitPackage_ - Begin automation after this package starts (optional). -- _appWaitActivity_ - Begin automation after this activity starts (optional). -- _intentAction_ - Intent to start (opt_ional). -- _intentCategory_ - Intent category to start (optional). -- _intentFlags_ - Flags to send to the intent (optional). -- _optionalIntentArguments_ - Optional arguments to the intent (optional). -- _dontStopAppOnReset_ - Should the app be stopped on reset (optional)? - - - - - -start_x -start_y -offset_x -offset_y -duration=1000 - -Swipe from one point to another point, for an optional duration. - -Args: - - start_x - x-coordinate at which to start - - start_y - y-coordinate at which to start - - offset_x - x-coordinate distance from start_x at which to stop - - offset_y - y-coordinate distance from start_y at which to stop - - duration - (optional) time to take the swipe, in ms. - -Usage: -| Swipe | 500 | 100 | 100 | 0 | 1000 | - -_*NOTE: *_ -Android 'Swipe' is not working properly, use ``offset_x`` and ``offset_y`` as if these are destination points. - - - - - -start_x -start_y -end_x -end_y -duration=1000 - -Swipe from one percent of the screen to another percent, for an optional duration. -Normal swipe fails to scale for different screen resolutions, this can be avoided using percent. - -Args: - - start_x - x-percent at which to start - - start_y - y-percent at which to start - - end_x - x-percent distance from start_x at which to stop - - end_y - y-percent distance from start_y at which to stop - - duration - (optional) time to take the swipe, in ms. - -Usage: -| Swipe By Percent | 90 | 50 | 10 | 50 | # Swipes screen from right to left. | - -_*NOTE: *_ -This also considers swipe acts different between iOS and Android. - -New in AppiumLibrary 1.4.5 - - - - - -index_or_alias - -Switches the active application by index or alias. - -`index_or_alias` is either application index (an integer) or alias -(a string). Index is got as the return value of `Open Application`. - -This keyword returns the index of the previous active application, -which can be used to switch back to that application later. - -Example: -| ${appium1}= | Open Application | http://localhost:4723/wd/hub | alias=MyApp1 | platformName=iOS | platformVersion=7.0 | deviceName='iPhone Simulator' | app=your.app | -| ${appium2}= | Open Application | http://localhost:4755/wd/hub | alias=MyApp2 | platformName=iOS | platformVersion=7.0 | deviceName='iPhone Simulator' | app=your.app | -| Click Element | sendHello | # Executed on appium running at localhost:4755 | -| Switch Application | ${appium1} | # Switch using index | -| Click Element | ackHello | # Executed on appium running at localhost:4723 | -| Switch Application | MyApp2 | # Switch using alias | -| Page Should Contain Text | ackHello Received | # Executed on appium running at localhost:4755 | - - - - - -context_name - -Switch to a new context - - - - - -locator -x_offset=None -y_offset=None -count=1 - -Tap element identified by ``locator``. - -Args: -- ``x_offset`` - (optional) x coordinate to tap, relative to the top left corner of the element. -- ``y_offset`` - (optional) y coordinate. If y is used, x must also be set, and vice versa -- ``count`` - can be used for multiple times of tap on that element - - - - - -text -exact_match=False -loglevel=INFO - -Verifies that element identified with text is visible. - -New in AppiumLibrary 1.4.5 - - - - - - -Toggle Touch ID enrolled state on iOS Simulator - -New in AppiumLibrary 1.5 - - - - - -match=True - -Simulate Touch ID on iOS Simulator - -`match` (boolean) whether the simulated fingerprint is valid (default true) - -New in AppiumLibrary 1.5 - - - - - -activity -timeout -interval=1 - -Wait for an activity: block until target activity presents -or time out. - -Android only. - - - _activity_ - target activity - - _timeout_ - max wait time, in seconds - - _interval_ - sleep interval between retries, in seconds - - - - - -locator -timeout=None -error=None - -Waits until element specified with `locator` is visible. - -Fails if `timeout` expires before the element is visible. See -`introduction` for more information about `timeout` and its -default value. - -`error` can be used to override the default error message. - -See also `Wait Until Page Contains`, `Wait Until Page Contains -Element`, `Wait For Condition` and BuiltIn keyword `Wait Until Keyword -Succeeds`. - - - - - -text -timeout=None -error=None - -Waits until `text` appears on current page. - -Fails if `timeout` expires before the text appears. See -`introduction` for more information about `timeout` and its -default value. - -`error` can be used to override the default error message. - -See also `Wait Until Page Does Not Contain`, -`Wait Until Page Contains Element`, -`Wait Until Page Does Not Contain Element` and -BuiltIn keyword `Wait Until Keyword Succeeds`. - - - - - -locator -timeout=None -error=None - -Waits until element specified with `locator` appears on current page. - -Fails if `timeout` expires before the element appears. See -`introduction` for more information about `timeout` and its -default value. - -`error` can be used to override the default error message. - -See also `Wait Until Page Contains`, -`Wait Until Page Does Not Contain` -`Wait Until Page Does Not Contain Element` -and BuiltIn keyword `Wait Until Keyword Succeeds`. - - - - - -text -timeout=None -error=None - -Waits until `text` disappears from current page. - -Fails if `timeout` expires before the `text` disappears. See -`introduction` for more information about `timeout` and its -default value. - -`error` can be used to override the default error message. - -See also `Wait Until Page Contains`, -`Wait Until Page Contains Element`, -`Wait Until Page Does Not Contain Element` and -BuiltIn keyword `Wait Until Keyword Succeeds`. - - - - - -locator -timeout=None -error=None - -Waits until element specified with `locator` disappears from current page. - -Fails if `timeout` expires before the element disappears. See -`introduction` for more information about `timeout` and its -default value. - -`error` can be used to override the default error message. - -See also `Wait Until Page Contains`, -`Wait Until Page Does Not Contain`, -`Wait Until Page Contains Element` and -BuiltIn keyword `Wait Until Keyword Succeeds`. - - - - - -xpath -count -error=None -loglevel=INFO - -Verifies that the page contains the given number of elements located by the given ``xpath``. - -One should not use the `xpath=` prefix for 'xpath'. XPath is assumed. - -| *Correct:* | -| Xpath Should Match X Times | //android.view.View[@text='Test'] | 1 | -| Incorrect: | -| Xpath Should Match X Times | xpath=//android.view.View[@text='Test'] | 1 | - -``error`` can be used to override the default error message. - -See `Log Source` for explanation about ``loglevel`` argument. - -New in AppiumLibrary 1.4. - - - - - -locator -percent=200% -steps=1 - -Zooms in on an element a certain amount. - - - - diff --git a/libspecs/BuiltIn.libspec b/libspecs/BuiltIn.libspec deleted file mode 100644 index 21605b8..0000000 --- a/libspecs/BuiltIn.libspec +++ /dev/null @@ -1,2923 +0,0 @@ - - -3.1.2 -global -yes -An always available standard library with often needed keywords. - -``BuiltIn`` is Robot Framework's standard library that provides a set -of generic keywords needed often. It is imported automatically and -thus always available. The provided keywords can be used, for example, -for verifications (e.g. `Should Be Equal`, `Should Contain`), -conversions (e.g. `Convert To Integer`) and for various other purposes -(e.g. `Log`, `Sleep`, `Run Keyword If`, `Set Global Variable`). - -== Table of contents == - -- `HTML error messages` -- `Evaluating expressions` -- `Boolean arguments` -- `Pattern matching` -- `Multiline string comparison` -- `String representations` -- `Shortcuts` -- `Keywords` - -= HTML error messages = - -Many of the keywords accept an optional error message to use if the keyword -fails, and it is possible to use HTML in these messages by prefixing them -with ``*HTML*``. See `Fail` keyword for a usage example. Notice that using -HTML in messages is not limited to BuiltIn library but works with any -error message. - -= Evaluating expressions = - -Many keywords, such as `Evaluate`, `Run Keyword If` and `Should Be True`, -accept an expression that is evaluated in Python. These expressions are -evaluated using Python's -[http://docs.python.org/library/functions.html#eval|eval] function so -that all Python built-ins like ``len()`` and ``int()`` are available. -`Evaluate` allows configuring the execution namespace with custom modules, -and other keywords have [http://docs.python.org/library/os.html|os] -and [http://docs.python.org/library/sys.html|sys] modules available -automatically. - -Examples: -| `Run Keyword If` | os.sep == '/' | Log | Not on Windows | -| ${random int} = | `Evaluate` | random.randint(0, 5) | modules=random | - -When a variable is used in the expressing using the normal ``${variable}`` -syntax, its value is replaces before the expression is evaluated. This -means that the value used in the expression will be the string -representation of the variable value, not the variable value itself. -This is not a problem with numbers and other objects that have a string -representation that can be evaluated directly, but with other objects -the behavior depends on the string representation. Most importantly, -strings must always be quoted, and if they can contain newlines, they must -be triple quoted. - -Examples: -| `Should Be True` | ${rc} < 10 | Return code greater than 10 | -| `Run Keyword If` | '${status}' == 'PASS' | Log | Passed | -| `Run Keyword If` | 'FAIL' in '''${output}''' | Log | Output contains FAIL | - -Starting from Robot Framework 2.9, variables themselves are automatically -available in the evaluation namespace. They can be accessed using special -variable syntax without the curly braces like ``$variable``. These -variables should never be quoted, and in fact they are not even replaced -inside strings. - -Examples: -| `Should Be True` | $rc < 10 | Return code greater than 10 | -| `Run Keyword If` | $status == 'PASS' | `Log` | Passed | -| `Run Keyword If` | 'FAIL' in $output | `Log` | Output contains FAIL | -| `Should Be True` | len($result) > 1 and $result[1] == 'OK' | - -Using the ``$variable`` syntax slows down expression evaluation a little. -This should not typically matter, but should be taken into account if -complex expressions are evaluated often and there are strict time -constrains. - -Notice that instead of creating complicated expressions, it is often better -to move the logic into a test library. That eases maintenance and can also -enhance execution speed. - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Keywords verifying something that allow dropping -actual and expected values from the possible error message also consider -string ``no values`` to be false. Other strings are considered true unless -the keyword documentation explicitly states otherwise, and other argument -types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Should Be Equal` | ${x} | ${y} | Custom error | values=True | # Strings are generally true. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=yes | # Same as the above. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=${TRUE} | # Python ``True`` is true. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=${42} | # Numbers other than 0 are true. | - -False examples: -| `Should Be Equal` | ${x} | ${y} | Custom error | values=False | # String ``false`` is false. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=no | # Also string ``no`` is false. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=${EMPTY} | # Empty string is false. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=${FALSE} | # Python ``False`` is false. | -| `Should Be Equal` | ${x} | ${y} | Custom error | values=no values | # ``no values`` works with ``values`` argument | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - -= Pattern matching = - -Many keywords accepts arguments as either glob or regular expression -patterns. - -== Glob patterns == - -Some keywords, for example `Should Match`, support so called -[http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where: - -| ``*`` | matches any string, even an empty string | -| ``?`` | matches any single character | -| ``[chars]`` | matches one character in the bracket | -| ``[!chars]`` | matches one character not in the bracket | -| ``[a-z]`` | matches one character from the range in the bracket | -| ``[!a-z]`` | matches one character not from the range in the bracket | - -Unlike with glob patterns normally, path separator characters ``/`` and -``\`` and the newline character ``\n`` are matches by the above -wildcards. - -Support for brackets like ``[abc]`` and ``[!a-z]`` is new in -Robot Framework 3.1 - -== Regular expressions == - -Some keywords, for example `Should Match Regexp`, support -[http://en.wikipedia.org/wiki/Regular_expression|regular expressions] -that are more powerful but also more complicated that glob patterns. -The regular expression support is implemented using Python's -[http://docs.python.org/library/re.html|re module] and its documentation -should be consulted for more information about the syntax. - -Because the backslash character (``\``) is an escape character in -Robot Framework test data, possible backslash characters in regular -expressions need to be escaped with another backslash like ``\\d\\w+``. -Strings that may contain special characters but should be handled -as literal strings, can be escaped with the `Regexp Escape` keyword. - -= Multiline string comparison = - -`Should Be Equal` and `Should Be Equal As Strings` report the failures using -[http://en.wikipedia.org/wiki/Diff_utility#Unified_format|unified diff -format] if both strings have more than two lines. New in Robot Framework -2.9.1. - -Example: -| ${first} = | `Catenate` | SEPARATOR=\n | Not in second | Same | Differs | Same | -| ${second} = | `Catenate` | SEPARATOR=\n | Same | Differs2 | Same | Not in first | -| `Should Be Equal` | ${first} | ${second} | - -Results in the following error message: - -| Multiline strings are different: -| --- first -| +++ second -| @@ -1,4 +1,4 @@ -| -Not in second -| Same -| -Differs -| +Differs2 -| Same -| +Not in first - -= String representations = - -Several keywords log values explicitly (e.g. `Log`) or implicitly (e.g. -`Should Be Equal` when there are failures). By default keywords log values -using "human readable" string representation, which means that strings -like ``Hello`` and numbers like ``42`` are logged as-is. Most of the time -this is the desired behavior, but there are some problems as well: - -- It is not possible to see difference between different objects that - have same string representation like string ``42`` and integer ``42``. - `Should Be Equal` and some other keywords add the type information to - the error message in these cases, though. - -- Non-printable characters such as the null byte are not visible. - -- Trailing whitespace is not visible. - -- Different newlines (``\r\n`` on Windows, ``\n`` elsewhere) cannot - be separated from each others. - -- There are several Unicode characters that are different but look the - same. One example is the Latin ``a`` (``\u0061``) and the Cyrillic - ``а`` (``\u0430``). Error messages like ``a != а`` are - not very helpful. - -- Some Unicode characters can be represented using - [https://en.wikipedia.org/wiki/Unicode_equivalence|different forms]. - For example, ``ä`` can be represented either as a single code point - ``\u00e4`` or using two code points ``\u0061`` and ``\u0308`` combined - together. Such forms are considered canonically equivalent, but strings - containing them are not considered equal when compared in Python. Error - messages like ``ä != ä`` are not that helpful either. - -- Containers such as lists and dictionaries are formatted into a single - line making it hard to see individual items they contain. - -To overcome the above problems, some keywords such as `Log` and -`Should Be Equal` have an optional ``formatter`` argument that can be -used to configure the string representation. The supported values are -``str`` (default), ``repr``, and ``ascii`` that work similarly as -[https://docs.python.org/library/functions.html|Python built-in functions] -with same names. More detailed semantics are explained below. - -The ``formatter`` argument is new in Robot Framework 3.1.2. - -== str == - -Use the "human readable" string representation. Equivalent to using -``str()`` in Python 3 and ``unicode()`` in Python 2. This is the default. - -== repr == - -Use the "machine readable" string representation. Similar to using -``repr()`` in Python, which means that strings like ``Hello`` are logged -like ``'Hello'``, newlines and non-printable characters are escaped like -``\n`` and ``\x00``, and so on. Non-ASCII characters are shown as-is -like ``ä`` in Python 3 and in escaped format like ``\xe4`` in Python 2. -Use ``ascii`` to always get the escaped format. - -There are also some enhancements compared to the standard ``repr()``: -- Bigger lists, dictionaries and other containers are pretty-printed so - that there is one item per row. -- On Python 2 the ``u`` prefix is omitted with Unicode strings and - the ``b`` prefix is added to byte strings. - -== ascii == - -Same as using ``ascii()`` in Python 3 or ``repr()`` in Python 2 where -``ascii()`` does not exist. Similar to using ``repr`` explained above -but with the following differences: - -- On Python 3 non-ASCII characters are escaped like ``\xe4`` instead of - showing them as-is like ``ä``. This makes it easier to see differences - between Unicode characters that look the same but are not equal. This - is how ``repr()`` works in Python 2. -- On Python 2 just uses the standard ``repr()`` meaning that Unicode - strings get the ``u`` prefix and no ``b`` prefix is added to byte - strings. -- Containers are not pretty-printed. - - -object -method_name -*args -**kwargs - -Calls the named method of the given object with the provided arguments. - -The possible return value from the method is returned and can be -assigned to a variable. Keyword fails both if the object does not have -a method with the given name or if executing the method raises an -exception. - -Support for ``**kwargs`` is new in Robot Framework 2.9. Since that -possible equal signs in other arguments must be escaped with a -backslash like ``\=``. - -Examples: -| Call Method | ${hashtable} | put | myname | myvalue | -| ${isempty} = | Call Method | ${hashtable} | isEmpty | | -| Should Not Be True | ${isempty} | | | | -| ${value} = | Call Method | ${hashtable} | get | myname | -| Should Be Equal | ${value} | myvalue | | | -| Call Method | ${object} | kwargs | name=value | foo=bar | -| Call Method | ${object} | positional | escaped\=equals | - - - - - -*items - -Catenates the given items together and returns the resulted string. - -By default, items are catenated with spaces, but if the first item -contains the string ``SEPARATOR=<sep>``, the separator ``<sep>`` is -used instead. Items are converted into strings when necessary. - -Examples: -| ${str1} = | Catenate | Hello | world | | -| ${str2} = | Catenate | SEPARATOR=--- | Hello | world | -| ${str3} = | Catenate | SEPARATOR= | Hello | world | -=> -| ${str1} = 'Hello world' -| ${str2} = 'Hello---world' -| ${str3} = 'Helloworld' - - - - - -*messages - -Displays the given messages in the log file as keyword arguments. - -This keyword does nothing with the arguments it receives, but as they -are visible in the log, this keyword can be used to display simple -messages. Given arguments are ignored so thoroughly that they can even -contain non-existing variables. If you are interested about variable -values, you can use the `Log` or `Log Many` keywords. - - - - - - -Skips the current for loop iteration and continues from the next. - -Skips the remaining keywords in the current for loop iteration and -continues from the next one. Can be used directly in a for loop or -in a keyword that the loop uses. - -Example: -| :FOR | ${var} | IN | @{VALUES} | -| | Run Keyword If | '${var}' == 'CONTINUE' | Continue For Loop | -| | Do Something | ${var} | - -See `Continue For Loop If` to conditionally continue a for loop without -using `Run Keyword If` or other wrapper keywords. - - - - - -condition - -Skips the current for loop iteration if the ``condition`` is true. - -A wrapper for `Continue For Loop` to continue a for loop based on -the given condition. The condition is evaluated using the same -semantics as with `Should Be True` keyword. - -Example: -| :FOR | ${var} | IN | @{VALUES} | -| | Continue For Loop If | '${var}' == 'CONTINUE' | -| | Do Something | ${var} | - - - - - -item -base=None -prefix=None -length=None - -Converts the given item to a binary string. - -The ``item``, with an optional ``base``, is first converted to an -integer using `Convert To Integer` internally. After that it -is converted to a binary number (base 2) represented as a -string such as ``1011``. - -The returned value can contain an optional ``prefix`` and can be -required to be of minimum ``length`` (excluding the prefix and a -possible minus sign). If the value is initially shorter than -the required length, it is padded with zeros. - -Examples: -| ${result} = | Convert To Binary | 10 | | | # Result is 1010 | -| ${result} = | Convert To Binary | F | base=16 | prefix=0b | # Result is 0b1111 | -| ${result} = | Convert To Binary | -2 | prefix=B | length=4 | # Result is -B0010 | - -See also `Convert To Integer`, `Convert To Octal` and `Convert To Hex`. - - - - - -item - -Converts the given item to Boolean true or false. - -Handles strings ``True`` and ``False`` (case-insensitive) as expected, -otherwise returns item's -[http://docs.python.org/library/stdtypes.html#truth|truth value] -using Python's ``bool()`` method. - - - - - -input -input_type=text - -Converts the given ``input`` to bytes according to the ``input_type``. - -Valid input types are listed below: - -- ``text:`` Converts text to bytes character by character. All - characters with ordinal below 256 can be used and are converted to - bytes with same values. Many characters are easiest to represent - using escapes like ``\x00`` or ``\xff``. Supports both Unicode - strings and bytes. - -- ``int:`` Converts integers separated by spaces to bytes. Similarly as - with `Convert To Integer`, it is possible to use binary, octal, or - hex values by prefixing the values with ``0b``, ``0o``, or ``0x``, - respectively. - -- ``hex:`` Converts hexadecimal values to bytes. Single byte is always - two characters long (e.g. ``01`` or ``FF``). Spaces are ignored and - can be used freely as a visual separator. - -- ``bin:`` Converts binary values to bytes. Single byte is always eight - characters long (e.g. ``00001010``). Spaces are ignored and can be - used freely as a visual separator. - -In addition to giving the input as a string, it is possible to use -lists or other iterables containing individual characters or numbers. -In that case numbers do not need to be padded to certain length and -they cannot contain extra spaces. - -Examples (last column shows returned bytes): -| ${bytes} = | Convert To Bytes | hyvä | | # hyv\xe4 | -| ${bytes} = | Convert To Bytes | \xff\x07 | | # \xff\x07 | -| ${bytes} = | Convert To Bytes | 82 70 | int | # RF | -| ${bytes} = | Convert To Bytes | 0b10 0x10 | int | # \x02\x10 | -| ${bytes} = | Convert To Bytes | ff 00 07 | hex | # \xff\x00\x07 | -| ${bytes} = | Convert To Bytes | 5246212121 | hex | # RF!!! | -| ${bytes} = | Convert To Bytes | 0000 1000 | bin | # \x08 | -| ${input} = | Create List | 1 | 2 | 12 | -| ${bytes} = | Convert To Bytes | ${input} | int | # \x01\x02\x0c | -| ${bytes} = | Convert To Bytes | ${input} | hex | # \x01\x02\x12 | - -Use `Encode String To Bytes` in ``String`` library if you need to -convert text to bytes using a certain encoding. - - - - - -item -base=None -prefix=None -length=None -lowercase=False - -Converts the given item to a hexadecimal string. - -The ``item``, with an optional ``base``, is first converted to an -integer using `Convert To Integer` internally. After that it -is converted to a hexadecimal number (base 16) represented as -a string such as ``FF0A``. - -The returned value can contain an optional ``prefix`` and can be -required to be of minimum ``length`` (excluding the prefix and a -possible minus sign). If the value is initially shorter than -the required length, it is padded with zeros. - -By default the value is returned as an upper case string, but the -``lowercase`` argument a true value (see `Boolean arguments`) turns -the value (but not the given prefix) to lower case. - -Examples: -| ${result} = | Convert To Hex | 255 | | | # Result is FF | -| ${result} = | Convert To Hex | -10 | prefix=0x | length=2 | # Result is -0x0A | -| ${result} = | Convert To Hex | 255 | prefix=X | lowercase=yes | # Result is Xff | - -See also `Convert To Integer`, `Convert To Binary` and `Convert To Octal`. - - - - - -item -base=None - -Converts the given item to an integer number. - -If the given item is a string, it is by default expected to be an -integer in base 10. There are two ways to convert from other bases: - -- Give base explicitly to the keyword as ``base`` argument. - -- Prefix the given string with the base so that ``0b`` means binary - (base 2), ``0o`` means octal (base 8), and ``0x`` means hex (base 16). - The prefix is considered only when ``base`` argument is not given and - may itself be prefixed with a plus or minus sign. - -The syntax is case-insensitive and possible spaces are ignored. - -Examples: -| ${result} = | Convert To Integer | 100 | | # Result is 100 | -| ${result} = | Convert To Integer | FF AA | 16 | # Result is 65450 | -| ${result} = | Convert To Integer | 100 | 8 | # Result is 64 | -| ${result} = | Convert To Integer | -100 | 2 | # Result is -4 | -| ${result} = | Convert To Integer | 0b100 | | # Result is 4 | -| ${result} = | Convert To Integer | -0x100 | | # Result is -256 | - -See also `Convert To Number`, `Convert To Binary`, `Convert To Octal`, -`Convert To Hex`, and `Convert To Bytes`. - - - - - -item -precision=None - -Converts the given item to a floating point number. - -If the optional ``precision`` is positive or zero, the returned number -is rounded to that number of decimal digits. Negative precision means -that the number is rounded to the closest multiple of 10 to the power -of the absolute precision. If a number is equally close to a certain -precision, it is always rounded away from zero. - -Examples: -| ${result} = | Convert To Number | 42.512 | | # Result is 42.512 | -| ${result} = | Convert To Number | 42.512 | 1 | # Result is 42.5 | -| ${result} = | Convert To Number | 42.512 | 0 | # Result is 43.0 | -| ${result} = | Convert To Number | 42.512 | -1 | # Result is 40.0 | - -Notice that machines generally cannot store floating point numbers -accurately. This may cause surprises with these numbers in general -and also when they are rounded. For more information see, for example, -these resources: - -- http://docs.python.org/tutorial/floatingpoint.html -- http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition - -If you want to avoid possible problems with floating point numbers, -you can implement custom keywords using Python's -[http://docs.python.org/library/decimal.html|decimal] or -[http://docs.python.org/library/fractions.html|fractions] modules. - -If you need an integer number, use `Convert To Integer` instead. - - - - - -item -base=None -prefix=None -length=None - -Converts the given item to an octal string. - -The ``item``, with an optional ``base``, is first converted to an -integer using `Convert To Integer` internally. After that it -is converted to an octal number (base 8) represented as a -string such as ``775``. - -The returned value can contain an optional ``prefix`` and can be -required to be of minimum ``length`` (excluding the prefix and a -possible minus sign). If the value is initially shorter than -the required length, it is padded with zeros. - -Examples: -| ${result} = | Convert To Octal | 10 | | | # Result is 12 | -| ${result} = | Convert To Octal | -F | base=16 | prefix=0 | # Result is -017 | -| ${result} = | Convert To Octal | 16 | prefix=oct | length=4 | # Result is oct0020 | - -See also `Convert To Integer`, `Convert To Binary` and `Convert To Hex`. - - - - - -item - -Converts the given item to a Unicode string. - -Strings are also [http://www.macchiato.com/unicode/nfc-faq| -NFC normalized]. - -Use `Encode String To Bytes` and `Decode Bytes To String` keywords -in ``String`` library if you need to convert between Unicode and byte -strings using different encodings. Use `Convert To Bytes` if you just -want to create byte strings. - - - - - -*items - -Creates and returns a dictionary based on the given ``items``. - -Items are typically given using the ``key=value`` syntax same way as -``&{dictionary}`` variables are created in the Variable table. Both -keys and values can contain variables, and possible equal sign in key -can be escaped with a backslash like ``escaped\=key=value``. It is -also possible to get items from existing dictionaries by simply using -them like ``&{dict}``. - -Alternatively items can be specified so that keys and values are given -separately. This and the ``key=value`` syntax can even be combined, -but separately given items must be first. If same key is used multiple -times, the last value has precedence. - -The returned dictionary is ordered, and values with strings as keys -can also be accessed using a convenient dot-access syntax like -``${dict.key}``. Technically the returned dictionary is Robot -Framework's own ``DotDict`` instance. If there is a need, it can be -converted into a regular Python ``dict`` instance by using the -`Convert To Dictionary` keyword from the Collections library. - -Examples: -| &{dict} = | Create Dictionary | key=value | foo=bar | | | # key=value syntax | -| Should Be True | ${dict} == {'key': 'value', 'foo': 'bar'} | -| &{dict2} = | Create Dictionary | key | value | foo | bar | # separate key and value | -| Should Be Equal | ${dict} | ${dict2} | -| &{dict} = | Create Dictionary | ${1}=${2} | &{dict} | foo=new | | # using variables | -| Should Be True | ${dict} == {1: 2, 'key': 'value', 'foo': 'new'} | -| Should Be Equal | ${dict.key} | value | | | | # dot-access | - -This keyword was changed in Robot Framework 2.9 in many ways: -- Moved from the Collections library to BuiltIn. -- Support also non-string keys in ``key=value`` syntax. -- Returned dictionary is ordered and dot-accessible (i.e. ``DotDict``). -- Old syntax to give keys and values separately was deprecated, but - deprecation was later removed in RF 3.0.1. - - - - - -*items - -Returns a list containing given items. - -The returned list can be assigned both to ``${scalar}`` and ``@{list}`` -variables. - -Examples: -| @{list} = | Create List | a | b | c | -| ${scalar} = | Create List | a | b | c | -| ${ints} = | Create List | ${1} | ${2} | ${3} | - - - - - -expression -modules=None -namespace=None - -Evaluates the given expression in Python and returns the results. - -``expression`` is evaluated in Python as explained in `Evaluating -expressions`. - -``modules`` argument can be used to specify a comma separated -list of Python modules to be imported and added to the evaluation -namespace. - -``namespace`` argument can be used to pass a custom evaluation -namespace as a dictionary. Possible ``modules`` are added to this -namespace. - -Variables used like ``${variable}`` are replaced in the expression -before evaluation. Variables are also available in the evaluation -namespace and can be accessed using special syntax ``$variable``. -This is a new feature in Robot Framework 2.9 and it is explained more -thoroughly in `Evaluating expressions`. - -Examples (expecting ``${result}`` is 3.14): -| ${status} = | Evaluate | 0 < ${result} < 10 | # Would also work with string '3.14' | -| ${status} = | Evaluate | 0 < $result < 10 | # Using variable itself, not string representation | -| ${random} = | Evaluate | random.randint(0, sys.maxint) | modules=random, sys | -| ${ns} = | Create Dictionary | x=${4} | y=${2} | -| ${result} = | Evaluate | x*10 + y | namespace=${ns} | -=> -| ${status} = True -| ${random} = <random integer> -| ${result} = 42 - - - - - - -Stops executing the enclosing for loop. - -Exits the enclosing for loop and continues execution after it. -Can be used directly in a for loop or in a keyword that the loop uses. - -Example: -| :FOR | ${var} | IN | @{VALUES} | -| | Run Keyword If | '${var}' == 'EXIT' | Exit For Loop | -| | Do Something | ${var} | - -See `Exit For Loop If` to conditionally exit a for loop without -using `Run Keyword If` or other wrapper keywords. - - - - - -condition - -Stops executing the enclosing for loop if the ``condition`` is true. - -A wrapper for `Exit For Loop` to exit a for loop based on -the given condition. The condition is evaluated using the same -semantics as with `Should Be True` keyword. - -Example: -| :FOR | ${var} | IN | @{VALUES} | -| | Exit For Loop If | '${var}' == 'EXIT' | -| | Do Something | ${var} | - - - - - -msg=None -*tags - -Fails the test with the given message and optionally alters its tags. - -The error message is specified using the ``msg`` argument. -It is possible to use HTML in the given error message, similarly -as with any other keyword accepting an error message, by prefixing -the error with ``*HTML*``. - -It is possible to modify tags of the current test case by passing tags -after the message. Tags starting with a hyphen (e.g. ``-regression``) -are removed and others added. Tags are modified using `Set Tags` and -`Remove Tags` internally, and the semantics setting and removing them -are the same as with these keywords. - -Examples: -| Fail | Test not ready | | | # Fails with the given message. | -| Fail | *HTML*<b>Test not ready</b> | | | # Fails using HTML in the message. | -| Fail | Test not ready | not-ready | | # Fails and adds 'not-ready' tag. | -| Fail | OS not supported | -regression | | # Removes tag 'regression'. | -| Fail | My message | tag | -t* | # Removes all tags starting with 't' except the newly added 'tag'. | - -See `Fatal Error` if you need to stop the whole test execution. - - - - - -msg=None - -Stops the whole test execution. - -The test or suite where this keyword is used fails with the provided -message, and subsequent tests fail with a canned message. -Possible teardowns will nevertheless be executed. - -See `Fail` if you only want to stop one test case unconditionally. - - - - - -item1 -item2 - -Returns and logs how many times ``item2`` is found from ``item1``. - -This keyword works with Python strings and lists and all objects -that either have ``count`` method or can be converted to Python lists. - -Example: -| ${count} = | Get Count | ${some item} | interesting value | -| Should Be True | 5 < ${count} < 10 | - - - - - -item - -Returns and logs the length of the given item as an integer. - -The item can be anything that has a length, for example, a string, -a list, or a mapping. The keyword first tries to get the length with -the Python function ``len``, which calls the item's ``__len__`` method -internally. If that fails, the keyword tries to call the item's -possible ``length`` and ``size`` methods directly. The final attempt is -trying to get the value of the item's ``length`` attribute. If all -these attempts are unsuccessful, the keyword fails. - -Examples: -| ${length} = | Get Length | Hello, world! | | -| Should Be Equal As Integers | ${length} | 13 | -| @{list} = | Create List | Hello, | world! | -| ${length} = | Get Length | ${list} | | -| Should Be Equal As Integers | ${length} | 2 | - -See also `Length Should Be`, `Should Be Empty` and `Should Not Be -Empty`. - - - - - -name=None -all=False - -Returns the currently active instance of the specified test library. - -This keyword makes it easy for test libraries to interact with -other test libraries that have state. This is illustrated by -the Python example below: - -| from robot.libraries.BuiltIn import BuiltIn -| -| def title_should_start_with(expected): -| seleniumlib = BuiltIn().get_library_instance('SeleniumLibrary') -| title = seleniumlib.get_title() -| if not title.startswith(expected): -| raise AssertionError("Title '%s' did not start with '%s'" -| % (title, expected)) - -It is also possible to use this keyword in the test data and -pass the returned library instance to another keyword. If a -library is imported with a custom name, the ``name`` used to get -the instance must be that name and not the original library name. - -If the optional argument ``all`` is given a true value, then a -dictionary mapping all library names to instances will be returned. -This feature is new in Robot Framework 2.9.2. - -Example: -| &{all libs} = | Get library instance | all=True | - - - - - -format=timestamp -time_=NOW - -Returns the given time in the requested format. - -*NOTE:* DateTime library contains much more flexible keywords for -getting the current date and time and for date and time handling in -general. - -How time is returned is determined based on the given ``format`` -string as follows. Note that all checks are case-insensitive. - -1) If ``format`` contains the word ``epoch``, the time is returned - in seconds after the UNIX epoch (1970-01-01 00:00:00 UTC). - The return value is always an integer. - -2) If ``format`` contains any of the words ``year``, ``month``, - ``day``, ``hour``, ``min``, or ``sec``, only the selected parts are - returned. The order of the returned parts is always the one - in the previous sentence and the order of words in ``format`` - is not significant. The parts are returned as zero-padded - strings (e.g. May -> ``05``). - -3) Otherwise (and by default) the time is returned as a - timestamp string in the format ``2006-02-24 15:08:31``. - -By default this keyword returns the current local time, but -that can be altered using ``time`` argument as explained below. -Note that all checks involving strings are case-insensitive. - -1) If ``time`` is a number, or a string that can be converted to - a number, it is interpreted as seconds since the UNIX epoch. - This documentation was originally written about 1177654467 - seconds after the epoch. - -2) If ``time`` is a timestamp, that time will be used. Valid - timestamp formats are ``YYYY-MM-DD hh:mm:ss`` and - ``YYYYMMDD hhmmss``. - -3) If ``time`` is equal to ``NOW`` (default), the current local - time is used. - -4) If ``time`` is equal to ``UTC``, the current time in - [http://en.wikipedia.org/wiki/Coordinated_Universal_Time|UTC] - is used. - -5) If ``time`` is in the format like ``NOW - 1 day`` or ``UTC + 1 hour - 30 min``, the current local/UTC time plus/minus the time - specified with the time string is used. The time string format - is described in an appendix of Robot Framework User Guide. - -Examples (expecting the current local time is 2006-03-29 15:06:21): -| ${time} = | Get Time | | | | -| ${secs} = | Get Time | epoch | | | -| ${year} = | Get Time | return year | | | -| ${yyyy} | ${mm} | ${dd} = | Get Time | year,month,day | -| @{time} = | Get Time | year month day hour min sec | | | -| ${y} | ${s} = | Get Time | seconds and year | | -=> -| ${time} = '2006-03-29 15:06:21' -| ${secs} = 1143637581 -| ${year} = '2006' -| ${yyyy} = '2006', ${mm} = '03', ${dd} = '29' -| @{time} = ['2006', '03', '29', '15', '06', '21'] -| ${y} = '2006' -| ${s} = '21' - -Examples (expecting the current local time is 2006-03-29 15:06:21 and -UTC time is 2006-03-29 12:06:21): -| ${time} = | Get Time | | 1177654467 | # Time given as epoch seconds | -| ${secs} = | Get Time | sec | 2007-04-27 09:14:27 | # Time given as a timestamp | -| ${year} = | Get Time | year | NOW | # The local time of execution | -| @{time} = | Get Time | hour min sec | NOW + 1h 2min 3s | # 1h 2min 3s added to the local time | -| @{utc} = | Get Time | hour min sec | UTC | # The UTC time of execution | -| ${hour} = | Get Time | hour | UTC - 1 hour | # 1h subtracted from the UTC time | -=> -| ${time} = '2007-04-27 09:14:27' -| ${secs} = 27 -| ${year} = '2006' -| @{time} = ['16', '08', '24'] -| @{utc} = ['12', '06', '21'] -| ${hour} = '11' - - - - - -name -default=None - -Returns variable value or ``default`` if the variable does not exist. - -The name of the variable can be given either as a normal variable name -(e.g. ``${NAME}``) or in escaped format (e.g. ``\${NAME}``). Notice -that the former has some limitations explained in `Set Suite Variable`. - -Examples: -| ${x} = | Get Variable Value | ${a} | default | -| ${y} = | Get Variable Value | ${a} | ${b} | -| ${z} = | Get Variable Value | ${z} | | -=> -| ${x} gets value of ${a} if ${a} exists and string 'default' otherwise -| ${y} gets value of ${a} if ${a} exists and value of ${b} otherwise -| ${z} is set to Python None if it does not exist previously - -See `Set Variable If` for another keyword to set variables dynamically. - - - - - -no_decoration=False - -Returns a dictionary containing all variables in the current scope. - -Variables are returned as a special dictionary that allows accessing -variables in space, case, and underscore insensitive manner similarly -as accessing variables in the test data. This dictionary supports all -same operations as normal Python dictionaries and, for example, -Collections library can be used to access or modify it. Modifying the -returned dictionary has no effect on the variables available in the -current scope. - -By default variables are returned with ``${}``, ``@{}`` or ``&{}`` -decoration based on variable types. Giving a true value (see `Boolean -arguments`) to the optional argument ``no_decoration`` will return -the variables without the decoration. This option is new in Robot -Framework 2.9. - -Example: -| ${example_variable} = | Set Variable | example value | -| ${variables} = | Get Variables | | -| Dictionary Should Contain Key | ${variables} | \${example_variable} | -| Dictionary Should Contain Key | ${variables} | \${ExampleVariable} | -| Set To Dictionary | ${variables} | \${name} | value | -| Variable Should Not Exist | \${name} | | | -| ${no decoration} = | Get Variables | no_decoration=Yes | -| Dictionary Should Contain Key | ${no decoration} | example_variable | - - - - - -name -*args - -Imports a library with the given name and optional arguments. - -This functionality allows dynamic importing of libraries while tests -are running. That may be necessary, if the library itself is dynamic -and not yet available when test data is processed. In a normal case, -libraries should be imported using the Library setting in the Setting -table. - -This keyword supports importing libraries both using library -names and physical paths. When paths are used, they must be -given in absolute format or found from -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath-jythonpath-and-ironpythonpath| -search path]. Forward slashes can be used as path separators in all -operating systems. - -It is possible to pass arguments to the imported library and also -named argument syntax works if the library supports it. ``WITH NAME`` -syntax can be used to give a custom name to the imported library. - -Examples: -| Import Library | MyLibrary | -| Import Library | ${CURDIR}/../Library.py | arg1 | named=arg2 | -| Import Library | ${LIBRARIES}/Lib.java | arg | WITH NAME | JavaLib | - - - - - -path - -Imports a resource file with the given path. - -Resources imported with this keyword are set into the test suite scope -similarly when importing them in the Setting table using the Resource -setting. - -The given path must be absolute or found from -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath-jythonpath-and-ironpythonpath| -search path]. Forward slashes can be used as path separator regardless -the operating system. - -Examples: -| Import Resource | ${CURDIR}/resource.txt | -| Import Resource | ${CURDIR}/../resources/resource.html | -| Import Resource | found_from_pythonpath.robot | - - - - - -path -*args - -Imports a variable file with the given path and optional arguments. - -Variables imported with this keyword are set into the test suite scope -similarly when importing them in the Setting table using the Variables -setting. These variables override possible existing variables with -the same names. This functionality can thus be used to import new -variables, for example, for each test in a test suite. - -The given path must be absolute or found from -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath-jythonpath-and-ironpythonpath| -search path]. Forward slashes can be used as path separator regardless -the operating system. - -Examples: -| Import Variables | ${CURDIR}/variables.py | | | -| Import Variables | ${CURDIR}/../vars/env.py | arg1 | arg2 | -| Import Variables | file_from_pythonpath.py | | | - - - - - -name -msg=None - -Fails unless the given keyword exists in the current scope. - -Fails also if there are more than one keywords with the same name. -Works both with the short name (e.g. ``Log``) and the full name -(e.g. ``BuiltIn.Log``). - -The default error message can be overridden with the ``msg`` argument. - -See also `Variable Should Exist`. - - - - - -item -length -msg=None - -Verifies that the length of the given item is correct. - -The length of the item is got using the `Get Length` keyword. The -default error message can be overridden with the ``msg`` argument. - - - - - -message -level=INFO -html=False -console=False -repr=False -formatter=str - -Logs the given message with the given level. - -Valid levels are TRACE, DEBUG, INFO (default), HTML, WARN, and ERROR. -Messages below the current active log level are ignored. See -`Set Log Level` keyword and ``--loglevel`` command line option -for more details about setting the level. - -Messages logged with the WARN or ERROR levels will be automatically -visible also in the console and in the Test Execution Errors section -in the log file. - -If the ``html`` argument is given a true value (see `Boolean -arguments`), the message will be considered HTML and special characters -such as ``<`` are not escaped. For example, logging -``<img src="image.png">`` creates an image when ``html`` is true, but -otherwise the message is that exact string. An alternative to using -the ``html`` argument is using the HTML pseudo log level. It logs -the message as HTML using the INFO level. - -If the ``console`` argument is true, the message will be written to -the console where test execution was started from in addition to -the log file. This keyword always uses the standard output stream -and adds a newline after the written message. Use `Log To Console` -instead if either of these is undesirable, - -The ``formatter`` argument controls how to format the string -representation of the message. Possible values are ``str`` (default), -``repr`` and ``ascii``, and they work similarly to Python built-in -functions with same names. When using ``repr``, bigger lists, -dictionaries and other containers are also pretty-printed so that -there is one item per row. For more details see `String -representations`. This is a new feature in Robot Framework 3.1.2. - -The old way to control string representation was using the ``repr`` -argument, and ``repr=True`` is still equivalent to using -``formatter=repr``. The ``repr`` argument will be deprecated in the -future, though, and using ``formatter`` is thus recommended. - -Examples: -| Log | Hello, world! | | | # Normal INFO message. | -| Log | Warning, world! | WARN | | # Warning. | -| Log | <b>Hello</b>, world! | html=yes | | # INFO message as HTML. | -| Log | <b>Hello</b>, world! | HTML | | # Same as above. | -| Log | <b>Hello</b>, world! | DEBUG | html=true | # DEBUG as HTML. | -| Log | Hello, console! | console=yes | | # Log also to the console. | -| Log | Null is \x00 | formatter=repr | | # Log ``'Null is \x00'``. | - -See `Log Many` if you want to log multiple messages in one go, and -`Log To Console` if you only want to write to the console. - - - - - -*messages - -Logs the given messages as separate entries using the INFO level. - -Supports also logging list and dictionary variable items individually. - -Examples: -| Log Many | Hello | ${var} | -| Log Many | @{list} | &{dict} | - -See `Log` and `Log To Console` keywords if you want to use alternative -log levels, use HTML, or log to the console. - - - - - -message -stream=STDOUT -no_newline=False - -Logs the given message to the console. - -By default uses the standard output stream. Using the standard error -stream is possibly by giving the ``stream`` argument value ``STDERR`` -(case-insensitive). - -By default appends a newline to the logged message. This can be -disabled by giving the ``no_newline`` argument a true value (see -`Boolean arguments`). - -Examples: -| Log To Console | Hello, console! | | -| Log To Console | Hello, stderr! | STDERR | -| Log To Console | Message starts here and is | no_newline=true | -| Log To Console | continued without newline. | | - -This keyword does not log the message to the normal log file. Use -`Log` keyword, possibly with argument ``console``, if that is desired. - - - - - -level=INFO - -Logs all variables in the current scope with given log level. - - - - - - -Does absolutely nothing. - - - - - -message -*tags - -Skips rest of the current test, setup, or teardown with PASS status. - -This keyword can be used anywhere in the test data, but the place where -used affects the behavior: - -- When used in any setup or teardown (suite, test or keyword), passes - that setup or teardown. Possible keyword teardowns of the started - keywords are executed. Does not affect execution or statuses - otherwise. -- When used in a test outside setup or teardown, passes that particular - test case. Possible test and keyword teardowns are executed. - -Possible continuable failures before this keyword is used, as well as -failures in executed teardowns, will fail the execution. - -It is mandatory to give a message explaining why execution was passed. -By default the message is considered plain text, but starting it with -``*HTML*`` allows using HTML formatting. - -It is also possible to modify test tags passing tags after the message -similarly as with `Fail` keyword. Tags starting with a hyphen -(e.g. ``-regression``) are removed and others added. Tags are modified -using `Set Tags` and `Remove Tags` internally, and the semantics -setting and removing them are the same as with these keywords. - -Examples: -| Pass Execution | All features available in this version tested. | -| Pass Execution | Deprecated test. | deprecated | -regression | - -This keyword is typically wrapped to some other keyword, such as -`Run Keyword If`, to pass based on a condition. The most common case -can be handled also with `Pass Execution If`: - -| Run Keyword If | ${rc} < 0 | Pass Execution | Negative values are cool. | -| Pass Execution If | ${rc} < 0 | Negative values are cool. | - -Passing execution in the middle of a test, setup or teardown should be -used with care. In the worst case it leads to tests that skip all the -parts that could actually uncover problems in the tested application. -In cases where execution cannot continue do to external factors, -it is often safer to fail the test case and make it non-critical. - - - - - -condition -message -*tags - -Conditionally skips rest of the current test, setup, or teardown with PASS status. - -A wrapper for `Pass Execution` to skip rest of the current test, -setup or teardown based the given ``condition``. The condition is -evaluated similarly as with `Should Be True` keyword, and ``message`` -and ``*tags`` have same semantics as with `Pass Execution`. - -Example: -| :FOR | ${var} | IN | @{VALUES} | -| | Pass Execution If | '${var}' == 'EXPECTED' | Correct value was found | -| | Do Something | ${var} | - - - - - -*patterns - -Returns each argument string escaped for use as a regular expression. - -This keyword can be used to escape strings to be used with -`Should Match Regexp` and `Should Not Match Regexp` keywords. - -Escaping is done with Python's ``re.escape()`` function. - -Examples: -| ${escaped} = | Regexp Escape | ${original} | -| @{strings} = | Regexp Escape | @{strings} | - - - - - -name_or_instance - -Rechecks what keywords the specified library provides. - -Can be called explicitly in the test data or by a library itself -when keywords it provides have changed. - -The library can be specified by its name or as the active instance of -the library. The latter is especially useful if the library itself -calls this keyword as a method. - -New in Robot Framework 2.9. - - - - - -*tags - -Removes given ``tags`` from the current test or all tests in a suite. - -Tags can be given exactly or using a pattern with ``*``, ``?`` and -``[chars]`` acting as wildcards. See the `Glob patterns` section -for more information. - -This keyword can affect either one test case or all test cases in a -test suite similarly as `Set Tags` keyword. - -The current tags are available as a built-in variable ``@{TEST TAGS}``. - -Example: -| Remove Tags | mytag | something-* | ?ython | - -See `Set Tags` if you want to add certain tags and `Fail` if you want -to fail the test case after setting and/or removing tags. - - - - - -repeat -name -*args - -Executes the specified keyword multiple times. - -``name`` and ``args`` define the keyword that is executed similarly as -with `Run Keyword`. ``repeat`` specifies how many times (as a count) or -how long time (as a timeout) the keyword should be executed. - -If ``repeat`` is given as count, it specifies how many times the -keyword should be executed. ``repeat`` can be given as an integer or -as a string that can be converted to an integer. If it is a string, -it can have postfix ``times`` or ``x`` (case and space insensitive) -to make the expression more explicit. - -If ``repeat`` is given as timeout, it must be in Robot Framework's -time format (e.g. ``1 minute``, ``2 min 3 s``). Using a number alone -(e.g. ``1`` or ``1.5``) does not work in this context. - -If ``repeat`` is zero or negative, the keyword is not executed at -all. This keyword fails immediately if any of the execution -rounds fails. - -Examples: -| Repeat Keyword | 5 times | Go to Previous Page | -| Repeat Keyword | ${var} | Some Keyword | arg1 | arg2 | -| Repeat Keyword | 2 minutes | Some Keyword | arg1 | arg2 | - -Specifying ``repeat`` as a timeout is new in Robot Framework 3.0. - - - - - -text - -Replaces variables in the given text with their current values. - -If the text contains undefined variables, this keyword fails. -If the given ``text`` contains only a single variable, its value is -returned as-is and it can be any object. Otherwise this keyword -always returns a string. - -Example: - -The file ``template.txt`` contains ``Hello ${NAME}!`` and variable -``${NAME}`` has the value ``Robot``. - -| ${template} = | Get File | ${CURDIR}/template.txt | -| ${message} = | Replace Variables | ${template} | -| Should Be Equal | ${message} | Hello Robot! | - - - - - -*return_values - -Returns from the enclosing user keyword. - -This keyword can be used to return from a user keyword with PASS status -without executing it fully. It is also possible to return values -similarly as with the ``[Return]`` setting. For more detailed information -about working with the return values, see the User Guide. - -This keyword is typically wrapped to some other keyword, such as -`Run Keyword If` or `Run Keyword If Test Passed`, to return based -on a condition: - -| Run Keyword If | ${rc} < 0 | Return From Keyword | -| Run Keyword If Test Passed | Return From Keyword | - -It is possible to use this keyword to return from a keyword also inside -a for loop. That, as well as returning values, is demonstrated by the -`Find Index` keyword in the following somewhat advanced example. -Notice that it is often a good idea to move this kind of complicated -logic into a test library. - -| ***** Variables ***** -| @{LIST} = foo baz -| -| ***** Test Cases ***** -| Example -| ${index} = Find Index baz @{LIST} -| Should Be Equal ${index} ${1} -| ${index} = Find Index non existing @{LIST} -| Should Be Equal ${index} ${-1} -| -| ***** Keywords ***** -| Find Index -| [Arguments] ${element} @{items} -| ${index} = Set Variable ${0} -| :FOR ${item} IN @{items} -| \ Run Keyword If '${item}' == '${element}' Return From Keyword ${index} -| \ ${index} = Set Variable ${index + 1} -| Return From Keyword ${-1} # Also [Return] would work here. - -The most common use case, returning based on an expression, can be -accomplished directly with `Return From Keyword If`. See also -`Run Keyword And Return` and `Run Keyword And Return If`. - - - - - -condition -*return_values - -Returns from the enclosing user keyword if ``condition`` is true. - -A wrapper for `Return From Keyword` to return based on the given -condition. The condition is evaluated using the same semantics as -with `Should Be True` keyword. - -Given the same example as in `Return From Keyword`, we can rewrite the -`Find Index` keyword as follows: - -| ***** Keywords ***** -| Find Index -| [Arguments] ${element} @{items} -| ${index} = Set Variable ${0} -| :FOR ${item} IN @{items} -| \ Return From Keyword If '${item}' == '${element}' ${index} -| \ ${index} = Set Variable ${index + 1} -| Return From Keyword ${-1} # Also [Return] would work here. - -See also `Run Keyword And Return` and `Run Keyword And Return If`. - - - - - -name -*args - -Executes the given keyword with the given arguments. - -Because the name of the keyword to execute is given as an argument, it -can be a variable and thus set dynamically, e.g. from a return value of -another keyword or from the command line. - - - - - -name -*args - -Runs the keyword and continues execution even if a failure occurs. - -The keyword name and arguments work as with `Run Keyword`. - -Example: -| Run Keyword And Continue On Failure | Fail | This is a stupid example | -| Log | This keyword is executed | - -The execution is not continued if the failure is caused by invalid syntax, -timeout, or fatal exception. -Since Robot Framework 2.9, variable errors are caught by this keyword. - - - - - -expected_error -name -*args - -Runs the keyword and checks that the expected error occurred. - -The keyword to execute and its arguments are specified using ``name`` -and ``*args`` exactly like with `Run Keyword`. - -The expected error must be given in the same format as in Robot -Framework reports. By default it is interpreted as a glob pattern -with ``*``, ``?`` and ``[chars]`` as wildcards, but starting from -Robot Framework 3.1 that can be changed by using various prefixes -explained in the table below. Prefixes are case-sensitive and they -must be separated from the actual message with a colon and an -optional space like ``PREFIX: Message`` or ``PREFIX:Message``. - -| = Prefix = | = Explanation = | -| ``EQUALS`` | Exact match. Especially useful if the error contains glob wildcards. | -| ``STARTS`` | Error must start with the specified error. | -| ``REGEXP`` | Regular expression match. | -| ``GLOB`` | Same as the default behavior. | - -See the `Pattern matching` section for more information about glob -patterns and regular expressions. - -If the expected error occurs, the error message is returned and it can -be further processed or tested if needed. If there is no error, or the -error does not match the expected error, this keyword fails. - -Examples: -| Run Keyword And Expect Error | My error | Keyword | arg | -| Run Keyword And Expect Error | ValueError: * | Some Keyword | -| Run Keyword And Expect Error | STARTS: ValueError: | Some Keyword | -| Run Keyword And Expect Error | EQUALS:No match for '//input[@type="text"]' | -| ... | Find Element | //input[@type="text"] | -| ${msg} = | Run Keyword And Expect Error | * | -| ... | Keyword | arg1 | arg2 | -| Log To Console | ${msg} | - -Errors caused by invalid syntax, timeouts, or fatal exceptions are not -caught by this keyword. -Since Robot Framework 2.9, variable errors are caught by this keyword. - - - - - -name -*args - -Runs the given keyword with the given arguments and ignores possible error. - -This keyword returns two values, so that the first is either string -``PASS`` or ``FAIL``, depending on the status of the executed keyword. -The second value is either the return value of the keyword or the -received error message. See `Run Keyword And Return Status` If you are -only interested in the execution status. - -The keyword name and arguments work as in `Run Keyword`. See -`Run Keyword If` for a usage example. - -Errors caused by invalid syntax, timeouts, or fatal exceptions are not -caught by this keyword. Otherwise this keyword itself never fails. -Since Robot Framework 2.9, variable errors are caught by this keyword. - - - - - -name -*args - -Runs the specified keyword and returns from the enclosing user keyword. - -The keyword to execute is defined with ``name`` and ``*args`` exactly -like with `Run Keyword`. After running the keyword, returns from the -enclosing user keyword and passes possible return value from the -executed keyword further. Returning from a keyword has exactly same -semantics as with `Return From Keyword`. - -Example: -| `Run Keyword And Return` | `My Keyword` | arg1 | arg2 | -| # Above is equivalent to: | -| ${result} = | `My Keyword` | arg1 | arg2 | -| `Return From Keyword` | ${result} | | | - -Use `Run Keyword And Return If` if you want to run keyword and return -based on a condition. - - - - - -condition -name -*args - -Runs the specified keyword and returns from the enclosing user keyword. - -A wrapper for `Run Keyword And Return` to run and return based on -the given ``condition``. The condition is evaluated using the same -semantics as with `Should Be True` keyword. - -Example: -| `Run Keyword And Return If` | ${rc} > 0 | `My Keyword` | arg1 | arg2 | -| # Above is equivalent to: | -| `Run Keyword If` | ${rc} > 0 | `Run Keyword And Return` | `My Keyword ` | arg1 | arg2 | - -Use `Return From Keyword If` if you want to return a certain value -based on a condition. - - - - - -name -*args - -Runs the given keyword with given arguments and returns the status as a Boolean value. - -This keyword returns Boolean ``True`` if the keyword that is executed -succeeds and ``False`` if it fails. This is useful, for example, in -combination with `Run Keyword If`. If you are interested in the error -message or return value, use `Run Keyword And Ignore Error` instead. - -The keyword name and arguments work as in `Run Keyword`. - -Example: -| ${passed} = | `Run Keyword And Return Status` | Keyword | args | -| `Run Keyword If` | ${passed} | Another keyword | - -Errors caused by invalid syntax, timeouts, or fatal exceptions are not -caught by this keyword. Otherwise this keyword itself never fails. - - - - - -condition -name -*args - -Runs the given keyword with the given arguments, if ``condition`` is true. - -The given ``condition`` is evaluated in Python as explained in -`Evaluating expressions`, and ``name`` and ``*args`` have same -semantics as with `Run Keyword`. - -Example, a simple if/else construct: -| ${status} | ${value} = | `Run Keyword And Ignore Error` | `My Keyword` | -| `Run Keyword If` | '${status}' == 'PASS' | `Some Action` | arg | -| `Run Keyword Unless` | '${status}' == 'PASS' | `Another Action` | - -In this example, only either `Some Action` or `Another Action` is -executed, based on the status of `My Keyword`. Instead of `Run Keyword -And Ignore Error` you can also use `Run Keyword And Return Status`. - -Variables used like ``${variable}``, as in the examples above, are -replaced in the expression before evaluation. Variables are also -available in the evaluation namespace and can be accessed using special -syntax ``$variable``. This is a new feature in Robot Framework 2.9 -and it is explained more thoroughly in `Evaluating expressions`. - -Example: -| `Run Keyword If` | $result is None or $result == 'FAIL' | `Keyword` | - -This keyword supports also optional ELSE and ELSE IF branches. Both -of them are defined in ``*args`` and must use exactly format ``ELSE`` -or ``ELSE IF``, respectively. ELSE branches must contain first the -name of the keyword to execute and then its possible arguments. ELSE -IF branches must first contain a condition, like the first argument -to this keyword, and then the keyword to execute and its possible -arguments. It is possible to have ELSE branch after ELSE IF and to -have multiple ELSE IF branches. Nested `Run Keyword If` usage is not -supported when using ELSE and/or ELSE IF branches. - -Given previous example, if/else construct can also be created like this: -| ${status} | ${value} = | `Run Keyword And Ignore Error` | `My Keyword` | -| `Run Keyword If` | '${status}' == 'PASS' | `Some Action` | arg | ELSE | `Another Action` | - -The return value of this keyword is the return value of the actually -executed keyword or Python ``None`` if no keyword was executed (i.e. -if ``condition`` was false). Hence, it is recommended to use ELSE -and/or ELSE IF branches to conditionally assign return values from -keyword to variables (see `Set Variable If` if you need to set fixed -values conditionally). This is illustrated by the example below: - -| ${var1} = | `Run Keyword If` | ${rc} == 0 | `Some keyword returning a value` | -| ... | ELSE IF | 0 < ${rc} < 42 | `Another keyword` | -| ... | ELSE IF | ${rc} < 0 | `Another keyword with args` | ${rc} | arg2 | -| ... | ELSE | `Final keyword to handle abnormal cases` | ${rc} | -| ${var2} = | `Run Keyword If` | ${condition} | `Some keyword` | - -In this example, ${var2} will be set to ``None`` if ${condition} is -false. - -Notice that ``ELSE`` and ``ELSE IF`` control words must be used -explicitly and thus cannot come from variables. If you need to use -literal ``ELSE`` and ``ELSE IF`` strings as arguments, you can escape -them with a backslash like ``\ELSE`` and ``\ELSE IF``. - -Python's [http://docs.python.org/library/os.html|os] and -[http://docs.python.org/library/sys.html|sys] modules are -automatically imported when evaluating the ``condition``. -Attributes they contain can thus be used in the condition: - -| `Run Keyword If` | os.sep == '/' | `Unix Keyword` | -| ... | ELSE IF | sys.platform.startswith('java') | `Jython Keyword` | -| ... | ELSE | `Windows Keyword` | - - - - - -name -*args - -Runs the given keyword with the given arguments, if all critical tests passed. - -This keyword can only be used in suite teardown. Trying to use it in -any other place will result in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - - - - - -name -*args - -Runs the given keyword with the given arguments, if all tests passed. - -This keyword can only be used in a suite teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - - - - - -name -*args - -Runs the given keyword with the given arguments, if any critical tests failed. - -This keyword can only be used in a suite teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - - - - - -name -*args - -Runs the given keyword with the given arguments, if one or more tests failed. - -This keyword can only be used in a suite teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - - - - - -name -*args - -Runs the given keyword with the given arguments, if the test failed. - -This keyword can only be used in a test teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - -Prior to Robot Framework 2.9 failures in test teardown itself were -not detected by this keyword. - - - - - -name -*args - -Runs the given keyword with the given arguments, if the test passed. - -This keyword can only be used in a test teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - -Prior to Robot Framework 2.9 failures in test teardown itself were -not detected by this keyword. - - - - - -name -*args - -Runs the given keyword if either a test or a keyword timeout has occurred. - -This keyword can only be used in a test teardown. Trying to use it -anywhere else results in an error. - -Otherwise, this keyword works exactly like `Run Keyword`, see its -documentation for more details. - - - - - -condition -name -*args - -Runs the given keyword with the given arguments if ``condition`` is false. - -See `Run Keyword If` for more information and an example. Notice that -this keyword does not support ``ELSE`` or ``ELSE IF`` branches like -`Run Keyword If` does, though. - - - - - -*keywords - -Executes all the given keywords in a sequence. - -This keyword is mainly useful in setups and teardowns when they need -to take care of multiple actions and creating a new higher level user -keyword would be an overkill. - -By default all arguments are expected to be keywords to be executed. - -Examples: -| `Run Keywords` | `Initialize database` | `Start servers` | `Clear logs` | -| `Run Keywords` | ${KW 1} | ${KW 2} | -| `Run Keywords` | @{KEYWORDS} | - -Keywords can also be run with arguments using upper case ``AND`` as -a separator between keywords. The keywords are executed so that the -first argument is the first keyword and proceeding arguments until -the first ``AND`` are arguments to it. First argument after the first -``AND`` is the second keyword and proceeding arguments until the next -``AND`` are its arguments. And so on. - -Examples: -| `Run Keywords` | `Initialize database` | db1 | AND | `Start servers` | server1 | server2 | -| `Run Keywords` | `Initialize database` | ${DB NAME} | AND | `Start servers` | @{SERVERS} | AND | `Clear logs` | -| `Run Keywords` | ${KW} | AND | @{KW WITH ARGS} | - -Notice that the ``AND`` control argument must be used explicitly and -cannot itself come from a variable. If you need to use literal ``AND`` -string as argument, you can either use variables or escape it with -a backslash like ``\AND``. - - - - - -name -*values - -Makes a variable available globally in all tests and suites. - -Variables set with this keyword are globally available in all -subsequent test suites, test cases and user keywords. Also variables -in variable tables are overridden. Variables assigned locally based -on keyword return values or by using `Set Test Variable` and -`Set Suite Variable` override these variables in that scope, but -the global value is not changed in those cases. - -In practice setting variables with this keyword has the same effect -as using command line options ``--variable`` and ``--variablefile``. -Because this keyword can change variables everywhere, it should be -used with care. - -See `Set Suite Variable` for more information and examples. - - - - - -*search_order - -Sets the resolution order to use when a name matches multiple keywords. - -The library search order is used to resolve conflicts when a keyword -name in the test data matches multiple keywords. The first library -(or resource, see below) containing the keyword is selected and that -keyword implementation used. If the keyword is not found from any library -(or resource), test executing fails the same way as when the search -order is not set. - -When this keyword is used, there is no need to use the long -``LibraryName.Keyword Name`` notation. For example, instead of -having - -| MyLibrary.Keyword | arg | -| MyLibrary.Another Keyword | -| MyLibrary.Keyword | xxx | - -you can have - -| Set Library Search Order | MyLibrary | -| Keyword | arg | -| Another Keyword | -| Keyword | xxx | - -This keyword can be used also to set the order of keywords in different -resource files. In this case resource names must be given without paths -or extensions like: - -| Set Library Search Order | resource | another_resource | - -*NOTE:* -- The search order is valid only in the suite where this keywords is used. -- Keywords in resources always have higher priority than - keywords in libraries regardless the search order. -- The old order is returned and can be used to reset the search order later. -- Library and resource names in the search order are both case and space - insensitive. - - - - - -level - -Sets the log threshold to the specified level and returns the old level. - -Messages below the level will not logged. The default logging level is -INFO, but it can be overridden with the command line option -``--loglevel``. - -The available levels: TRACE, DEBUG, INFO (default), WARN, ERROR and NONE (no -logging). - - - - - -doc -append=False -top=False - -Sets documentation for the current test suite. - -By default the possible existing documentation is overwritten, but -this can be changed using the optional ``append`` argument similarly -as with `Set Test Message` keyword. - -This keyword sets the documentation of the current suite by default. -If the optional ``top`` argument is given a true value (see `Boolean -arguments`), the documentation of the top level suite is altered -instead. - -The documentation of the current suite is available as a built-in -variable ``${SUITE DOCUMENTATION}``. - - - - - -name -value -append=False -top=False - -Sets metadata for the current test suite. - -By default possible existing metadata values are overwritten, but -this can be changed using the optional ``append`` argument similarly -as with `Set Test Message` keyword. - -This keyword sets the metadata of the current suite by default. -If the optional ``top`` argument is given a true value (see `Boolean -arguments`), the metadata of the top level suite is altered instead. - -The metadata of the current suite is available as a built-in variable -``${SUITE METADATA}`` in a Python dictionary. Notice that modifying this -variable directly has no effect on the actual metadata the suite has. - - - - - -name -*values - -Makes a variable available everywhere within the scope of the current suite. - -Variables set with this keyword are available everywhere within the -scope of the currently executed test suite. Setting variables with this -keyword thus has the same effect as creating them using the Variable -table in the test data file or importing them from variable files. - -Possible child test suites do not see variables set with this keyword -by default. Starting from Robot Framework 2.9, that can be controlled -by using ``children=<option>`` as the last argument. If the specified -``<option>`` is a non-empty string or any other value considered true -in Python, the variable is set also to the child suites. Parent and -sibling suites will never see variables set with this keyword. - -The name of the variable can be given either as a normal variable name -(e.g. ``${NAME}``) or in escaped format as ``\${NAME}`` or ``$NAME``. -Variable value can be given using the same syntax as when variables -are created in the Variable table. - -If a variable already exists within the new scope, its value will be -overwritten. Otherwise a new variable is created. If a variable already -exists within the current scope, the value can be left empty and the -variable within the new scope gets the value within the current scope. - -Examples: -| Set Suite Variable | ${SCALAR} | Hello, world! | -| Set Suite Variable | ${SCALAR} | Hello, world! | children=true | -| Set Suite Variable | @{LIST} | First item | Second item | -| Set Suite Variable | &{DICT} | key=value | foo=bar | -| ${ID} = | Get ID | -| Set Suite Variable | ${ID} | - -To override an existing value with an empty value, use built-in -variables ``${EMPTY}``, ``@{EMPTY}`` or ``&{EMPTY}``: - -| Set Suite Variable | ${SCALAR} | ${EMPTY} | -| Set Suite Variable | @{LIST} | @{EMPTY} | -| Set Suite Variable | &{DICT} | &{EMPTY} | - -*NOTE:* If the variable has value which itself is a variable (escaped -or not), you must always use the escaped format to set the variable: - -Example: -| ${NAME} = | Set Variable | \${var} | -| Set Suite Variable | ${NAME} | value | # Sets variable ${var} | -| Set Suite Variable | \${NAME} | value | # Sets variable ${NAME} | - -This limitation applies also to `Set Test Variable`, `Set Global -Variable`, `Variable Should Exist`, `Variable Should Not Exist` and -`Get Variable Value` keywords. - - - - - -*tags - -Adds given ``tags`` for the current test or all tests in a suite. - -When this keyword is used inside a test case, that test gets -the specified tags and other tests are not affected. - -If this keyword is used in a suite setup, all test cases in -that suite, recursively, gets the given tags. It is a failure -to use this keyword in a suite teardown. - -The current tags are available as a built-in variable ``@{TEST TAGS}``. - -See `Remove Tags` if you want to remove certain tags and `Fail` if -you want to fail the test case after setting and/or removing tags. - - - - - -name -*values - -Makes a variable available everywhere within the scope of the current task. - -This is an alias for `Set Test Variable` that is more applicable when -creating tasks, not tests. New in RF 3.1. - - - - - -doc -append=False - -Sets documentation for the current test case. - -By default the possible existing documentation is overwritten, but -this can be changed using the optional ``append`` argument similarly -as with `Set Test Message` keyword. - -The current test documentation is available as a built-in variable -``${TEST DOCUMENTATION}``. This keyword can not be used in suite -setup or suite teardown. - - - - - -message -append=False - -Sets message for the current test case. - -If the optional ``append`` argument is given a true value (see `Boolean -arguments`), the given ``message`` is added after the possible earlier -message by joining the messages with a space. - -In test teardown this keyword can alter the possible failure message, -but otherwise failures override messages set by this keyword. Notice -that in teardown the message is available as a built-in variable -``${TEST MESSAGE}``. - -It is possible to use HTML format in the message by starting the message -with ``*HTML*``. - -Examples: -| Set Test Message | My message | | -| Set Test Message | is continued. | append=yes | -| Should Be Equal | ${TEST MESSAGE} | My message is continued. | -| Set Test Message | `*`HTML`*` <b>Hello!</b> | | - -This keyword can not be used in suite setup or suite teardown. - - - - - -name -*values - -Makes a variable available everywhere within the scope of the current test. - -Variables set with this keyword are available everywhere within the -scope of the currently executed test case. For example, if you set a -variable in a user keyword, it is available both in the test case level -and also in all other user keywords used in the current test. Other -test cases will not see variables set with this keyword. - -See `Set Suite Variable` for more information and examples. - - - - - -*values - -Returns the given values which can then be assigned to a variables. - -This keyword is mainly used for setting scalar variables. -Additionally it can be used for converting a scalar variable -containing a list to a list variable or to multiple scalar variables. -It is recommended to use `Create List` when creating new lists. - -Examples: -| ${hi} = | Set Variable | Hello, world! | -| ${hi2} = | Set Variable | I said: ${hi} | -| ${var1} | ${var2} = | Set Variable | Hello | world | -| @{list} = | Set Variable | ${list with some items} | -| ${item1} | ${item2} = | Set Variable | ${list with 2 items} | - -Variables created with this keyword are available only in the -scope where they are created. See `Set Global Variable`, -`Set Test Variable` and `Set Suite Variable` for information on how to -set variables so that they are available also in a larger scope. - - - - - -condition -*values - -Sets variable based on the given condition. - -The basic usage is giving a condition and two values. The -given condition is first evaluated the same way as with the -`Should Be True` keyword. If the condition is true, then the -first value is returned, and otherwise the second value is -returned. The second value can also be omitted, in which case -it has a default value None. This usage is illustrated in the -examples below, where ``${rc}`` is assumed to be zero. - -| ${var1} = | Set Variable If | ${rc} == 0 | zero | nonzero | -| ${var2} = | Set Variable If | ${rc} > 0 | value1 | value2 | -| ${var3} = | Set Variable If | ${rc} > 0 | whatever | | -=> -| ${var1} = 'zero' -| ${var2} = 'value2' -| ${var3} = None - -It is also possible to have 'else if' support by replacing the -second value with another condition, and having two new values -after it. If the first condition is not true, the second is -evaluated and one of the values after it is returned based on -its truth value. This can be continued by adding more -conditions without a limit. - -| ${var} = | Set Variable If | ${rc} == 0 | zero | -| ... | ${rc} > 0 | greater than zero | less then zero | -| | -| ${var} = | Set Variable If | -| ... | ${rc} == 0 | zero | -| ... | ${rc} == 1 | one | -| ... | ${rc} == 2 | two | -| ... | ${rc} > 2 | greater than two | -| ... | ${rc} < 0 | less than zero | - -Use `Get Variable Value` if you need to set variables -dynamically based on whether a variable exist or not. - - - - - -item -msg=None - -Verifies that the given item is empty. - -The length of the item is got using the `Get Length` keyword. The -default error message can be overridden with the ``msg`` argument. - - - - - -first -second -msg=None -values=True -ignore_case=False -formatter=str - -Fails if the given objects are unequal. - -Optional ``msg``, ``values`` and ``formatter`` arguments specify how -to construct the error message if this keyword fails: - -- If ``msg`` is not given, the error message is ``<first> != <second>``. -- If ``msg`` is given and ``values`` gets a true value (default), - the error message is ``<msg>: <first> != <second>``. -- If ``msg`` is given and ``values`` gets a false value (see - `Boolean arguments`), the error message is simply ``<msg>``. -- ``formatter`` controls how to format the values. Possible values are - ``str`` (default), ``repr`` and ``ascii``, and they work similarly - as Python built-in functions with same names. See `String - representations` for more details. - -If ``ignore_case`` is given a true value (see `Boolean arguments`) and -both arguments are strings, comparison is done case-insensitively. -If both arguments are multiline strings, this keyword uses -`multiline string comparison`. - -Examples: -| Should Be Equal | ${x} | expected | -| Should Be Equal | ${x} | expected | Custom error message | -| Should Be Equal | ${x} | expected | Custom message | values=False | -| Should Be Equal | ${x} | expected | ignore_case=True | formatter=repr | - -``ignore_case`` and ``formatter`` are new features in Robot Framework -3.0.1 and 3.1.2, respectively. - - - - - -first -second -msg=None -values=True -base=None - -Fails if objects are unequal after converting them to integers. - -See `Convert To Integer` for information how to convert integers from -other bases than 10 using ``base`` argument or ``0b/0o/0x`` prefixes. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``. - -Examples: -| Should Be Equal As Integers | 42 | ${42} | Error message | -| Should Be Equal As Integers | ABCD | abcd | base=16 | -| Should Be Equal As Integers | 0b1011 | 11 | - - - - - -first -second -msg=None -values=True -precision=6 - -Fails if objects are unequal after converting them to real numbers. - -The conversion is done with `Convert To Number` keyword using the -given ``precision``. - -Examples: -| Should Be Equal As Numbers | ${x} | 1.1 | | # Passes if ${x} is 1.1 | -| Should Be Equal As Numbers | 1.123 | 1.1 | precision=1 | # Passes | -| Should Be Equal As Numbers | 1.123 | 1.4 | precision=0 | # Passes | -| Should Be Equal As Numbers | 112.3 | 75 | precision=-2 | # Passes | - -As discussed in the documentation of `Convert To Number`, machines -generally cannot store floating point numbers accurately. Because of -this limitation, comparing floats for equality is problematic and -a correct approach to use depends on the context. This keyword uses -a very naive approach of rounding the numbers before comparing them, -which is both prone to rounding errors and does not work very well if -numbers are really big or small. For more information about comparing -floats, and ideas on how to implement your own context specific -comparison algorithm, see -http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/. - -If you want to avoid possible problems with floating point numbers, -you can implement custom keywords using Python's -[http://docs.python.org/library/decimal.html|decimal] or -[http://docs.python.org/library/fractions.html|fractions] modules. - -See `Should Not Be Equal As Numbers` for a negative version of this -keyword and `Should Be Equal` for an explanation on how to override -the default error message with ``msg`` and ``values``. - - - - - -first -second -msg=None -values=True -ignore_case=False -formatter=str - -Fails if objects are unequal after converting them to strings. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg``, ``values`` and ``formatter``. - -If ``ignore_case`` is given a true value (see `Boolean arguments`), -comparison is done case-insensitively. If both arguments are -multiline strings, this keyword uses `multiline string comparison`. - -Strings are always [http://www.macchiato.com/unicode/nfc-faq| -NFC normalized]. - -``ignore_case`` and ``formatter`` are new features in Robot Framework -3.0.1 and 3.1.2, respectively. - - - - - -condition -msg=None - -Fails if the given condition is not true. - -If ``condition`` is a string (e.g. ``${rc} < 10``), it is evaluated as -a Python expression as explained in `Evaluating expressions` and the -keyword status is decided based on the result. If a non-string item is -given, the status is got directly from its -[http://docs.python.org/library/stdtypes.html#truth|truth value]. - -The default error message (``<condition> should be true``) is not very -informative, but it can be overridden with the ``msg`` argument. - -Examples: -| Should Be True | ${rc} < 10 | -| Should Be True | '${status}' == 'PASS' | # Strings must be quoted | -| Should Be True | ${number} | # Passes if ${number} is not zero | -| Should Be True | ${list} | # Passes if ${list} is not empty | - -Variables used like ``${variable}``, as in the examples above, are -replaced in the expression before evaluation. Variables are also -available in the evaluation namespace and can be accessed using special -syntax ``$variable``. This is a new feature in Robot Framework 2.9 -and it is explained more thoroughly in `Evaluating expressions`. - -Examples: -| Should Be True | $rc < 10 | -| Should Be True | $status == 'PASS' | # Expected string must be quoted | - -`Should Be True` automatically imports Python's -[http://docs.python.org/library/os.html|os] and -[http://docs.python.org/library/sys.html|sys] modules that contain -several useful attributes: - -| Should Be True | os.linesep == '\n' | # Unixy | -| Should Be True | os.linesep == '\r\n' | # Windows | -| Should Be True | sys.platform == 'darwin' | # OS X | -| Should Be True | sys.platform.startswith('java') | # Jython | - - - - - -container -item -msg=None -values=True -ignore_case=False - -Fails if ``container`` does not contain ``item`` one or more times. - -Works with strings, lists, and anything that supports Python's ``in`` -operator. - -See `Should Be Equal` for an explanation on how to override the default -error message with arguments ``msg`` and ``values``. - -If ``ignore_case`` is given a true value (see `Boolean arguments`) and -compared items are strings, it indicates that comparison should be -case-insensitive. If the ``container`` is a list-like object, string -items in it are compared case-insensitively. New option in Robot -Framework 3.0.1. - -Examples: -| Should Contain | ${output} | PASS | -| Should Contain | ${some list} | value | msg=Failure! | values=False | -| Should Contain | ${some list} | value | ignore_case=True | - - - - - -container -*items -**configuration - -Fails if ``container`` does not contain any of the ``*items``. - -Works with strings, lists, and anything that supports Python's ``in`` -operator. - -Supports additional configuration parameters ``msg``, ``values`` -and ``ignore_case``, which have exactly the same semantics as arguments -with same names have with `Should Contain`. These arguments must -always be given using ``name=value`` syntax after all ``items``. - -Note that possible equal signs in ``items`` must be escaped with -a backslash (e.g. ``foo\=bar``) to avoid them to be passed in -as ``**configuration``. - -Examples: -| Should Contain Any | ${string} | substring 1 | substring 2 | -| Should Contain Any | ${list} | item 1 | item 2 | item 3 | -| Should Contain Any | ${list} | item 1 | item 2 | item 3 | ignore_case=True | -| Should Contain Any | ${list} | @{items} | msg=Custom message | values=False | - -New in Robot Framework 3.0.1. - - - - - -item1 -item2 -count -msg=None -ignore_case=False - -Fails if ``item1`` does not contain ``item2`` ``count`` times. - -Works with strings, lists and all objects that `Get Count` works -with. The default error message can be overridden with ``msg`` and -the actual count is always logged. - -If ``ignore_case`` is given a true value (see `Boolean arguments`) and -compared items are strings, it indicates that comparison should be -case-insensitive. If the ``item1`` is a list-like object, string -items in it are compared case-insensitively. New option in Robot -Framework 3.0.1. - -Examples: -| Should Contain X Times | ${output} | hello | 2 | -| Should Contain X Times | ${some list} | value | 3 | ignore_case=True | - - - - - -str1 -str2 -msg=None -values=True -ignore_case=False - -Fails if the string ``str1`` does not end with the string ``str2``. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -string -pattern -msg=None -values=True -ignore_case=False - -Fails if the given ``string`` does not match the given ``pattern``. - -Pattern matching is similar as matching files in a shell with -``*``, ``?`` and ``[chars]`` acting as wildcards. See the -`Glob patterns` section for more information. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -string -pattern -msg=None -values=True - -Fails if ``string`` does not match ``pattern`` as a regular expression. - -See the `Regular expressions` section for more information about -regular expressions and how to use then in Robot Framework test data. - -Notice that the given pattern does not need to match the whole string. -For example, the pattern ``ello`` matches the string ``Hello world!``. -If a full match is needed, the ``^`` and ``$`` characters can be used -to denote the beginning and end of the string, respectively. -For example, ``^ello$`` only matches the exact string ``ello``. - -Possible flags altering how the expression is parsed (e.g. -``re.IGNORECASE``, ``re.MULTILINE``) must be embedded to the -pattern like ``(?im)pattern``. The most useful flags are ``i`` -(case-insensitive), ``m`` (multiline mode), ``s`` (dotall mode) -and ``x`` (verbose). - -If this keyword passes, it returns the portion of the string that -matched the pattern. Additionally, the possible captured groups are -returned. - -See the `Should Be Equal` keyword for an explanation on how to override -the default error message with the ``msg`` and ``values`` arguments. - -Examples: -| Should Match Regexp | ${output} | \\d{6} | # Output contains six numbers | -| Should Match Regexp | ${output} | ^\\d{6}$ | # Six numbers and nothing more | -| ${ret} = | Should Match Regexp | Foo: 42 | (?i)foo: \\d+ | -| ${match} | ${group1} | ${group2} = | -| ... | Should Match Regexp | Bar: 43 | (Foo|Bar): (\\d+) | -=> -| ${ret} = 'Foo: 42' -| ${match} = 'Bar: 43' -| ${group1} = 'Bar' -| ${group2} = '43' - - - - - -item -msg=None - -Verifies that the given item is not empty. - -The length of the item is got using the `Get Length` keyword. The -default error message can be overridden with the ``msg`` argument. - - - - - -first -second -msg=None -values=True -ignore_case=False - -Fails if the given objects are equal. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``. - -If ``ignore_case`` is given a true value (see `Boolean arguments`) and -both arguments are strings, comparison is done case-insensitively. -New option in Robot Framework 3.0.1. - - - - - -first -second -msg=None -values=True -base=None - -Fails if objects are equal after converting them to integers. - -See `Convert To Integer` for information how to convert integers from -other bases than 10 using ``base`` argument or ``0b/0o/0x`` prefixes. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``. - -See `Should Be Equal As Integers` for some usage examples. - - - - - -first -second -msg=None -values=True -precision=6 - -Fails if objects are equal after converting them to real numbers. - -The conversion is done with `Convert To Number` keyword using the -given ``precision``. - -See `Should Be Equal As Numbers` for examples on how to use -``precision`` and why it does not always work as expected. See also -`Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``. - - - - - -first -second -msg=None -values=True -ignore_case=False - -Fails if objects are equal after converting them to strings. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``. - -If ``ignore_case`` is given a true value (see `Boolean arguments`), -comparison is done case-insensitively. - -Strings are always [http://www.macchiato.com/unicode/nfc-faq| -NFC normalized]. - -``ignore_case`` is a new feature in Robot Framework 3.0.1. - - - - - -condition -msg=None - -Fails if the given condition is true. - -See `Should Be True` for details about how ``condition`` is evaluated -and how ``msg`` can be used to override the default error message. - - - - - -container -item -msg=None -values=True -ignore_case=False - -Fails if ``container`` contains ``item`` one or more times. - -Works with strings, lists, and anything that supports Python's ``in`` -operator. - -See `Should Be Equal` for an explanation on how to override the default -error message with arguments ``msg`` and ``values``. ``ignore_case`` -has exactly the same semantics as with `Should Contain`. - -Examples: -| Should Not Contain | ${some list} | value | -| Should Not Contain | ${output} | FAILED | ignore_case=True | - - - - - -container -*items -**configuration - -Fails if ``container`` contains one or more of the ``*items``. - -Works with strings, lists, and anything that supports Python's ``in`` -operator. - -Supports additional configuration parameters ``msg``, ``values`` -and ``ignore_case``, which have exactly the same semantics as arguments -with same names have with `Should Contain`. These arguments must -always be given using ``name=value`` syntax after all ``items``. - -Note that possible equal signs in ``items`` must be escaped with -a backslash (e.g. ``foo\=bar``) to avoid them to be passed in -as ``**configuration``. - -Examples: -| Should Not Contain Any | ${string} | substring 1 | substring 2 | -| Should Not Contain Any | ${list} | item 1 | item 2 | item 3 | -| Should Not Contain Any | ${list} | item 1 | item 2 | item 3 | ignore_case=True | -| Should Not Contain Any | ${list} | @{items} | msg=Custom message | values=False | - -New in Robot Framework 3.0.1. - - - - - -str1 -str2 -msg=None -values=True -ignore_case=False - -Fails if the string ``str1`` ends with the string ``str2``. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -string -pattern -msg=None -values=True -ignore_case=False - -Fails if the given ``string`` matches the given ``pattern``. - -Pattern matching is similar as matching files in a shell with -``*``, ``?`` and ``[chars]`` acting as wildcards. See the -`Glob patterns` section for more information. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -string -pattern -msg=None -values=True - -Fails if ``string`` matches ``pattern`` as a regular expression. - -See `Should Match Regexp` for more information about arguments. - - - - - -str1 -str2 -msg=None -values=True -ignore_case=False - -Fails if the string ``str1`` starts with the string ``str2``. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -str1 -str2 -msg=None -values=True -ignore_case=False - -Fails if the string ``str1`` does not start with the string ``str2``. - -See `Should Be Equal` for an explanation on how to override the default -error message with ``msg`` and ``values``, as well as for semantics -of the ``ignore_case`` option. - - - - - -time_ -reason=None - -Pauses the test executed for the given time. - -``time`` may be either a number or a time string. Time strings are in -a format such as ``1 day 2 hours 3 minutes 4 seconds 5milliseconds`` or -``1d 2h 3m 4s 5ms``, and they are fully explained in an appendix of -Robot Framework User Guide. Optional `reason` can be used to explain why -sleeping is necessary. Both the time slept and the reason are logged. - -Examples: -| Sleep | 42 | -| Sleep | 1.5 | -| Sleep | 2 minutes 10 seconds | -| Sleep | 10s | Wait for a reply | - - - - - -name -msg=None - -Fails unless the given variable exists within the current scope. - -The name of the variable can be given either as a normal variable name -(e.g. ``${NAME}``) or in escaped format (e.g. ``\${NAME}``). Notice -that the former has some limitations explained in `Set Suite Variable`. - -The default error message can be overridden with the ``msg`` argument. - -See also `Variable Should Not Exist` and `Keyword Should Exist`. - - - - - -name -msg=None - -Fails if the given variable exists within the current scope. - -The name of the variable can be given either as a normal variable name -(e.g. ``${NAME}``) or in escaped format (e.g. ``\${NAME}``). Notice -that the former has some limitations explained in `Set Suite Variable`. - -The default error message can be overridden with the ``msg`` argument. - -See also `Variable Should Exist` and `Keyword Should Exist`. - - - - - -retry -retry_interval -name -*args - -Runs the specified keyword and retries if it fails. - -``name`` and ``args`` define the keyword that is executed similarly -as with `Run Keyword`. How long to retry running the keyword is -defined using ``retry`` argument either as timeout or count. -``retry_interval`` is the time to wait before trying to run the -keyword again after the previous run has failed. - -If ``retry`` is given as timeout, it must be in Robot Framework's -time format (e.g. ``1 minute``, ``2 min 3 s``, ``4.5``) that is -explained in an appendix of Robot Framework User Guide. If it is -given as count, it must have ``times`` or ``x`` postfix (e.g. -``5 times``, ``10 x``). ``retry_interval`` must always be given in -Robot Framework's time format. - -If the keyword does not succeed regardless of retries, this keyword -fails. If the executed keyword passes, its return value is returned. - -Examples: -| Wait Until Keyword Succeeds | 2 min | 5 sec | My keyword | argument | -| ${result} = | Wait Until Keyword Succeeds | 3x | 200ms | My keyword | - -All normal failures are caught by this keyword. Errors caused by -invalid syntax, test or keyword timeouts, or fatal exceptions (caused -e.g. by `Fatal Error`) are not caught. - -Running the same keyword multiple times inside this keyword can create -lots of output and considerably increase the size of the generated -output files. It is possible to remove unnecessary keywords from -the outputs using ``--RemoveKeywords WUKS`` command line option. - -Support for specifying ``retry`` as a number of times to retry is -a new feature in Robot Framework 2.9. -Since Robot Framework 2.9, variable errors are caught by this keyword. - - - - diff --git a/libspecs/Collections.libspec b/libspecs/Collections.libspec deleted file mode 100644 index 7045e69..0000000 --- a/libspecs/Collections.libspec +++ /dev/null @@ -1,911 +0,0 @@ - - -3.1.2 -global -yes -A test library providing keywords for handling lists and dictionaries. - -``Collections`` is Robot Framework's standard library that provides a -set of keywords for handling Python lists and dictionaries. This -library has keywords, for example, for modifying and getting -values from lists and dictionaries (e.g. `Append To List`, `Get -From Dictionary`) and for verifying their contents (e.g. `Lists -Should Be Equal`, `Dictionary Should Contain Value`). - -= Related keywords in BuiltIn = - -Following keywords in the BuiltIn library can also be used with -lists and dictionaries: - -| = Keyword Name = | = Applicable With = | = Comment = | -| `Create List` | lists | -| `Create Dictionary` | dicts | Was in Collections until RF 2.9. | -| `Get Length` | both | -| `Length Should Be` | both | -| `Should Be Empty` | both | -| `Should Not Be Empty` | both | -| `Should Contain` | both | -| `Should Not Contain` | both | -| `Should Contain X Times` | lists | -| `Should Not Contain X Times` | lists | -| `Get Count` | lists | - -= Using with list-like and dictionary-like objects = - -List keywords that do not alter the given list can also be used -with tuples, and to some extend also with other iterables. -`Convert To List` can be used to convert tuples and other iterables -to Python ``list`` objects. - -Similarly dictionary keywords can, for most parts, be used with other -mappings. `Convert To Dictionary` can be used if real Python ``dict`` -objects are needed. - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Keywords verifying something that allow dropping -actual and expected values from the possible error message also consider -string ``no values`` to be false. Other strings are considered true -regardless their value, and other argument types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=True | # Strings are generally true. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=yes | # Same as the above. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${TRUE} | # Python ``True`` is true. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${42} | # Numbers other than 0 are true. | - -False examples: -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=False | # String ``false`` is false. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=no | # Also string ``no`` is false. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${EMPTY} | # Empty string is false. | -| `Should Contain Match` | ${list} | ${pattern} | case_insensitive=${FALSE} | # Python ``False`` is false. | -| `Lists Should Be Equal` | ${x} | ${y} | Custom error | values=no values | # ``no values`` works with ``values`` argument | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - -= Data in examples = - -List related keywords use variables in format ``${Lx}`` in their examples. -They mean lists with as many alphabetic characters as specified by ``x``. -For example, ``${L1}`` means ``['a']`` and ``${L3}`` means -``['a', 'b', 'c']``. - -Dictionary keywords use similar ``${Dx}`` variables. For example, ``${D1}`` -means ``{'a': 1}`` and ``${D3}`` means ``{'a': 1, 'b': 2, 'c': 3}``. - - -list_ -*values - -Adds ``values`` to the end of ``list``. - -Example: -| Append To List | ${L1} | xxx | | | -| Append To List | ${L2} | x | y | z | -=> -| ${L1} = ['a', 'xxx'] -| ${L2} = ['a', 'b', 'x', 'y', 'z'] - - - - - -*lists - -Combines the given ``lists`` together and returns the result. - -The given lists are not altered by this keyword. - -Example: -| ${x} = | Combine List | ${L1} | ${L2} | | -| ${y} = | Combine List | ${L1} | ${L2} | ${L1} | -=> -| ${x} = ['a', 'a', 'b'] -| ${y} = ['a', 'a', 'b', 'a'] -| ${L1} and ${L2} are not changed. - - - - - -item - -Converts the given ``item`` to a Python ``dict`` type. - -Mainly useful for converting other mappings to normal dictionaries. -This includes converting Robot Framework's own ``DotDict`` instances -that it uses if variables are created using the ``&{var}`` syntax. - -Use `Create Dictionary` from the BuiltIn library for constructing new -dictionaries. - -New in Robot Framework 2.9. - - - - - -item - -Converts the given ``item`` to a Python ``list`` type. - -Mainly useful for converting tuples and other iterable to lists. -Use `Create List` from the BuiltIn library for constructing new lists. - - - - - -dictionary -deepcopy=False - -Returns a copy of the given dictionary. - -The ``deepcopy`` argument controls should the returned dictionary be -a [https://docs.python.org/library/copy.html|shallow or deep copy]. -By default returns a shallow copy, but that can be changed by giving -``deepcopy`` a true value (see `Boolean arguments`). This is a new -option in Robot Framework 3.1.2. Earlier versions always returned -shallow copies. - -The given dictionary is never altered by this keyword. - - - - - -list_ -deepcopy=False - -Returns a copy of the given list. - -If the optional ``deepcopy`` is given a true value, the returned -list is a deep copy. New option in Robot Framework 3.1.2. - -The given list is never altered by this keyword. - - - - - -list_ -value -start=0 -end=None - -Returns the number of occurrences of the given ``value`` in ``list``. - -The search can be narrowed to the selected sublist by the ``start`` and -``end`` indexes having the same semantics as with `Get Slice From List` -keyword. The given list is never altered by this keyword. - -Example: -| ${x} = | Count Values In List | ${L3} | b | -=> -| ${x} = 1 -| ${L3} is not changed - - - - - -dict1 -dict2 -msg=None -values=True - -Fails if the given dictionaries are not equal. - -First the equality of dictionaries' keys is checked and after that all -the key value pairs. If there are differences between the values, those -are listed in the error message. The types of the dictionaries do not -need to be same. - -See `Lists Should Be Equal` for more information about configuring -the error message with ``msg`` and ``values`` arguments. - - - - - -dictionary -key -value -msg=None - -An item of ``key`` / ``value`` must be found in a ``dictionary``. - -Value is converted to unicode for comparison. - -Use the ``msg`` argument to override the default error message. - - - - - -dictionary -key -msg=None - -Fails if ``key`` is not found from ``dictionary``. - -Use the ``msg`` argument to override the default error message. - - - - - -dict1 -dict2 -msg=None -values=True - -Fails unless all items in ``dict2`` are found from ``dict1``. - -See `Lists Should Be Equal` for more information about configuring -the error message with ``msg`` and ``values`` arguments. - - - - - -dictionary -value -msg=None - -Fails if ``value`` is not found from ``dictionary``. - -Use the ``msg`` argument to override the default error message. - - - - - -dictionary -key -msg=None - -Fails if ``key`` is found from ``dictionary``. - -Use the ``msg`` argument to override the default error message. - - - - - -dictionary -value -msg=None - -Fails if ``value`` is found from ``dictionary``. - -Use the ``msg`` argument to override the default error message. - - - - - -dictionary -sort_keys=True - -Returns items of the given ``dictionary`` as a list. - -Uses `Get Dictionary Keys` to get keys and then returns corresponding -items. By default keys are sorted and items returned in that order, -but this can be changed by giving ``sort_keys`` a false value (see -`Boolean arguments`). Notice that with Python 3.5 and earlier -dictionary order is undefined unless using ordered dictionaries. - -Items are returned as a flat list so that first item is a key, -second item is a corresponding value, third item is the second key, -and so on. - -The given ``dictionary`` is never altered by this keyword. - -Example: -| ${sorted} = | Get Dictionary Items | ${D3} | -| ${unsorted} = | Get Dictionary Items | ${D3} | sort_keys=False | -=> -| ${sorted} = ['a', 1, 'b', 2, 'c', 3] -| ${unsorted} = ['b', 2, 'a', 1, 'c', 3] # Order depends on Python version. - -``sort_keys`` is a new option in Robot Framework 3.1.2. Earlier items -were always sorted based on keys. - - - - - -dictionary -sort_keys=True - -Returns keys of the given ``dictionary`` as a list. - -By default keys are returned in sorted order (assuming they are -sortable), but they can be returned in the original order by giving -``sort_keys`` a false value (see `Boolean arguments`). Notice that -with Python 3.5 and earlier dictionary order is undefined unless using -ordered dictionaries. - -The given ``dictionary`` is never altered by this keyword. - -Example: -| ${sorted} = | Get Dictionary Keys | ${D3} | -| ${unsorted} = | Get Dictionary Keys | ${D3} | sort_keys=False | -=> -| ${sorted} = ['a', 'b', 'c'] -| ${unsorted} = ['b', 'a', 'c'] # Order depends on Python version. - -``sort_keys`` is a new option in Robot Framework 3.1.2. Earlier keys -were always sorted. - - - - - -dictionary -sort_keys=True - -Returns values of the given ``dictionary`` as a list. - -Uses `Get Dictionary Keys` to get keys and then returns corresponding -values. By default keys are sorted and values returned in that order, -but this can be changed by giving ``sort_keys`` a false value (see -`Boolean arguments`). Notice that with Python 3.5 and earlier -dictionary order is undefined unless using ordered dictionaries. - -The given ``dictionary`` is never altered by this keyword. - -Example: -| ${sorted} = | Get Dictionary Values | ${D3} | -| ${unsorted} = | Get Dictionary Values | ${D3} | sort_keys=False | -=> -| ${sorted} = [1, 2, 3] -| ${unsorted} = [2, 1, 3] # Order depends on Python version. - -``sort_keys`` is a new option in Robot Framework 3.1.2. Earlier values -were always sorted based on keys. - - - - - -dictionary -key - -Returns a value from the given ``dictionary`` based on the given ``key``. - -If the given ``key`` cannot be found from the ``dictionary``, this -keyword fails. - -The given dictionary is never altered by this keyword. - -Example: -| ${value} = | Get From Dictionary | ${D3} | b | -=> -| ${value} = 2 - - - - - -list_ -index - -Returns the value specified with an ``index`` from ``list``. - -The given list is never altered by this keyword. - -Index ``0`` means the first position, ``1`` the second, and so on. -Similarly, ``-1`` is the last position, ``-2`` the second last, and so on. -Using an index that does not exist on the list causes an error. -The index can be either an integer or a string that can be converted -to an integer. - -Examples (including Python equivalents in comments): -| ${x} = | Get From List | ${L5} | 0 | # L5[0] | -| ${y} = | Get From List | ${L5} | -2 | # L5[-2] | -=> -| ${x} = 'a' -| ${y} = 'd' -| ${L5} is not changed - - - - - -list_ -value -start=0 -end=None - -Returns the index of the first occurrence of the ``value`` on the list. - -The search can be narrowed to the selected sublist by the ``start`` and -``end`` indexes having the same semantics as with `Get Slice From List` -keyword. In case the value is not found, -1 is returned. The given list -is never altered by this keyword. - -Example: -| ${x} = | Get Index From List | ${L5} | d | -=> -| ${x} = 3 -| ${L5} is not changed - - - - - -list -pattern -case_insensitive=False -whitespace_insensitive=False - -Returns the count of matches to ``pattern`` in ``list``. - -For more information on ``pattern``, ``case_insensitive``, and -``whitespace_insensitive``, see `Should Contain Match`. - -Examples: -| ${count}= | Get Match Count | ${list} | a* | # ${count} will be the count of strings beginning with 'a' | -| ${count}= | Get Match Count | ${list} | regexp=a.* | # ${matches} will be the count of strings beginning with 'a' (regexp version) | -| ${count}= | Get Match Count | ${list} | a* | case_insensitive=${True} | # ${matches} will be the count of strings beginning with 'a' or 'A' | - - - - - -list -pattern -case_insensitive=False -whitespace_insensitive=False - -Returns a list of matches to ``pattern`` in ``list``. - -For more information on ``pattern``, ``case_insensitive``, and -``whitespace_insensitive``, see `Should Contain Match`. - -Examples: -| ${matches}= | Get Matches | ${list} | a* | # ${matches} will contain any string beginning with 'a' | -| ${matches}= | Get Matches | ${list} | regexp=a.* | # ${matches} will contain any string beginning with 'a' (regexp version) | -| ${matches}= | Get Matches | ${list} | a* | case_insensitive=${True} | # ${matches} will contain any string beginning with 'a' or 'A' | - - - - - -list_ -start=0 -end=None - -Returns a slice of the given list between ``start`` and ``end`` indexes. - -The given list is never altered by this keyword. - -If both ``start`` and ``end`` are given, a sublist containing values -from ``start`` to ``end`` is returned. This is the same as -``list[start:end]`` in Python. To get all items from the beginning, -use 0 as the start value, and to get all items until and including -the end, use ``None`` (default) as the end value. - -Using ``start`` or ``end`` not found on the list is the same as using -the largest (or smallest) available index. - -Examples (incl. Python equivalents in comments): -| ${x} = | Get Slice From List | ${L5} | 2 | 4 | # L5[2:4] | -| ${y} = | Get Slice From List | ${L5} | 1 | | # L5[1:None] | -| ${z} = | Get Slice From List | ${L5} | | -2 | # L5[0:-2] | -=> -| ${x} = ['c', 'd'] -| ${y} = ['b', 'c', 'd', 'e'] -| ${z} = ['a', 'b', 'c'] -| ${L5} is not changed - - - - - -list_ -index -value - -Inserts ``value`` into ``list`` to the position specified with ``index``. - -Index ``0`` adds the value into the first position, ``1`` to the second, -and so on. Inserting from right works with negative indices so that -``-1`` is the second last position, ``-2`` third last, and so on. Use -`Append To List` to add items to the end of the list. - -If the absolute value of the index is greater than -the length of the list, the value is added at the end -(positive index) or the beginning (negative index). An index -can be given either as an integer or a string that can be -converted to an integer. - -Example: -| Insert Into List | ${L1} | 0 | xxx | -| Insert Into List | ${L2} | ${-1} | xxx | -=> -| ${L1} = ['xxx', 'a'] -| ${L2} = ['a', 'xxx', 'b'] - - - - - -dictionary -*keys - -Keeps the given ``keys`` in the ``dictionary`` and removes all other. - -If the given ``key`` cannot be found from the ``dictionary``, it -is ignored. - -Example: -| Keep In Dictionary | ${D5} | b | x | d | -=> -| ${D5} = {'b': 2, 'd': 4} - - - - - -list1 -list2 -msg=None -values=True - -Fails if not all of the elements in ``list2`` are found in ``list1``. - -The order of values and the number of values are not taken into -account. - -See `Lists Should Be Equal` for more information about configuring -the error message with ``msg`` and ``values`` arguments. - - - - - -list_ -value -msg=None - -Fails if the ``value`` is not found from ``list``. - -Use the ``msg`` argument to override the default error message. - - - - - -list_ -msg=None - -Fails if any element in the ``list`` is found from it more than once. - -The default error message lists all the elements that were found -from the ``list`` multiple times, but it can be overridden by giving -a custom ``msg``. All multiple times found items and their counts are -also logged. - -This keyword works with all iterables that can be converted to a list. -The original iterable is never altered. - - - - - -list_ -value -msg=None - -Fails if the ``value`` is found from ``list``. - -Use the ``msg`` argument to override the default error message. - - - - - -list1 -list2 -msg=None -values=True -names=None - -Fails if given lists are unequal. - -The keyword first verifies that the lists have equal lengths, and then -it checks are all their values equal. Possible differences between the -values are listed in the default error message like ``Index 4: ABC != -Abc``. The types of the lists do not need to be the same. For example, -Python tuple and list with same content are considered equal. - -The error message can be configured using ``msg`` and ``values`` -arguments: -- If ``msg`` is not given, the default error message is used. -- If ``msg`` is given and ``values`` gets a value considered true - (see `Boolean arguments`), the error message starts with the given - ``msg`` followed by a newline and the default message. -- If ``msg`` is given and ``values`` is not given a true value, - the error message is just the given ``msg``. - -Optional ``names`` argument can be used for naming the indices shown in -the default error message. It can either be a list of names matching -the indices in the lists or a dictionary where keys are indices that -need to be named. It is not necessary to name all of the indices. When -using a dictionary, keys can be either integers or strings that can be -converted to integers. - -Examples: -| ${names} = | Create List | First Name | Family Name | Email | -| Lists Should Be Equal | ${people1} | ${people2} | names=${names} | -| ${names} = | Create Dictionary | 0=First Name | 2=Email | -| Lists Should Be Equal | ${people1} | ${people2} | names=${names} | - -If the items in index 2 would differ in the above examples, the error -message would contain a row like ``Index 2 (email): name@foo.com != -name@bar.com``. - - - - - -dictionary -level=INFO - -Logs the size and contents of the ``dictionary`` using given ``level``. - -Valid levels are TRACE, DEBUG, INFO (default), and WARN. - -If you only want to log the size, use keyword `Get Length` from -the BuiltIn library. - - - - - -list_ -level=INFO - -Logs the length and contents of the ``list`` using given ``level``. - -Valid levels are TRACE, DEBUG, INFO (default), and WARN. - -If you only want to the length, use keyword `Get Length` from -the BuiltIn library. - - - - - -dictionary -key -default= - -Pops the given ``key`` from the ``dictionary`` and returns its value. - -By default the keyword fails if the given ``key`` cannot be found from -the ``dictionary``. If optional ``default`` value is given, it will be -returned instead of failing. - -Example: -| ${val}= | Pop From Dictionary | ${D3} | b | -=> -| ${val} = 2 -| ${D3} = {'a': 1, 'c': 3} - -New in Robot Framework 2.9.2. - - - - - -list_ - -Returns a list without duplicates based on the given ``list``. - -Creates and returns a new list that contains all items in the given -list so that one item can appear only once. Order of the items in -the new list is the same as in the original except for missing -duplicates. Number of the removed duplicates is logged. - - - - - -dictionary -*keys - -Removes the given ``keys`` from the ``dictionary``. - -If the given ``key`` cannot be found from the ``dictionary``, it -is ignored. - -Example: -| Remove From Dictionary | ${D3} | b | x | y | -=> -| ${D3} = {'a': 1, 'c': 3} - - - - - -list_ -index - -Removes and returns the value specified with an ``index`` from ``list``. - -Index ``0`` means the first position, ``1`` the second and so on. -Similarly, ``-1`` is the last position, ``-2`` the second last, and so on. -Using an index that does not exist on the list causes an error. -The index can be either an integer or a string that can be converted -to an integer. - -Example: -| ${x} = | Remove From List | ${L2} | 0 | -=> -| ${x} = 'a' -| ${L2} = ['b'] - - - - - -list_ -*values - -Removes all occurrences of given ``values`` from ``list``. - -It is not an error if a value does not exist in the list at all. - -Example: -| Remove Values From List | ${L4} | a | c | e | f | -=> -| ${L4} = ['b', 'd'] - - - - - -list_ - -Reverses the given list in place. - -Note that the given list is changed and nothing is returned. Use -`Copy List` first, if you need to keep also the original order. - -| Reverse List | ${L3} | -=> -| ${L3} = ['c', 'b', 'a'] - - - - - -list_ -index -value - -Sets the value of ``list`` specified by ``index`` to the given ``value``. - -Index ``0`` means the first position, ``1`` the second and so on. -Similarly, ``-1`` is the last position, ``-2`` second last, and so on. -Using an index that does not exist on the list causes an error. -The index can be either an integer or a string that can be converted to -an integer. - -Example: -| Set List Value | ${L3} | 1 | xxx | -| Set List Value | ${L3} | -1 | yyy | -=> -| ${L3} = ['a', 'xxx', 'yyy'] - - - - - -dictionary -*key_value_pairs -**items - -Adds the given ``key_value_pairs`` and ``items`` to the ``dictionary``. - -Giving items as ``key_value_pairs`` means giving keys and values -as separate arguments: - -| Set To Dictionary | ${D1} | key | value | second | ${2} | -=> -| ${D1} = {'a': 1, 'key': 'value', 'second': 2} - -| Set To Dictionary | ${D1} | key=value | second=${2} | - -The latter syntax is typically more convenient to use, but it has -a limitation that keys must be strings. - -If given keys already exist in the dictionary, their values are updated. - - - - - -list -pattern -msg=None -case_insensitive=False -whitespace_insensitive=False - -Fails if ``pattern`` is not found in ``list``. - -By default, pattern matching is similar to matching files in a shell -and is case-sensitive and whitespace-sensitive. In the pattern syntax, -``*`` matches to anything and ``?`` matches to any single character. You -can also prepend ``glob=`` to your pattern to explicitly use this pattern -matching behavior. - -If you prepend ``regexp=`` to your pattern, your pattern will be used -according to the Python -[http://docs.python.org/library/re.html|re module] regular expression -syntax. Important note: Backslashes are an escape character, and must -be escaped with another backslash (e.g. ``regexp=\\d{6}`` to search for -``\d{6}``). See `BuiltIn.Should Match Regexp` for more details. - -If ``case_insensitive`` is given a true value (see `Boolean arguments`), -the pattern matching will ignore case. - -If ``whitespace_insensitive`` is given a true value (see `Boolean -arguments`), the pattern matching will ignore whitespace. - -Non-string values in lists are ignored when matching patterns. - -Use the ``msg`` argument to override the default error message. - -See also ``Should Not Contain Match``. - -Examples: -| Should Contain Match | ${list} | a* | | | # Match strings beginning with 'a'. | -| Should Contain Match | ${list} | regexp=a.* | | | # Same as the above but with regexp. | -| Should Contain Match | ${list} | regexp=\\d{6} | | | # Match strings containing six digits. | -| Should Contain Match | ${list} | a* | case_insensitive=True | | # Match strings beginning with 'a' or 'A'. | -| Should Contain Match | ${list} | ab* | whitespace_insensitive=yes | | # Match strings beginning with 'ab' with possible whitespace ignored. | -| Should Contain Match | ${list} | ab* | whitespace_insensitive=true | case_insensitive=true | # Same as the above but also ignore case. | - - - - - -list -pattern -msg=None -case_insensitive=False -whitespace_insensitive=False - -Fails if ``pattern`` is found in ``list``. - -Exact opposite of `Should Contain Match` keyword. See that keyword -for information about arguments and usage in general. - - - - - -list_ - -Sorts the given list in place. - -Sorting fails if items in the list are not comparable with each others. -On Python 2 most objects are comparable, but on Python 3 comparing, -for example, strings with numbers is not possible. - -Note that the given list is changed and nothing is returned. Use -`Copy List` first, if you need to keep also the original order. - - - - diff --git a/libspecs/DateTime.libspec b/libspecs/DateTime.libspec deleted file mode 100644 index 59e2981..0000000 --- a/libspecs/DateTime.libspec +++ /dev/null @@ -1,512 +0,0 @@ - - -3.1.2 -global -yes -A test library for handling date and time values. - -``DateTime`` is a Robot Framework standard library that supports creating and -converting date and time values (e.g. `Get Current Date`, `Convert Time`), -as well as doing simple calculations with them (e.g. `Subtract Time From Date`, -`Add Time To Time`). It supports dates and times in various formats, and can -also be used by other libraries programmatically. - -= Table of Contents = - -- `Terminology` -- `Date formats` -- `Time formats` -- `Millisecond handling` -- `Programmatic usage` -- `Shortcuts` -- `Keywords` - -= Terminology = - -In the context of this library, ``date`` and ``time`` generally have following -meanings: - -- ``date``: An entity with both date and time components but without any - timezone information. For example, ``2014-06-11 10:07:42``. -- ``time``: A time interval. For example, ``1 hour 20 minutes`` or ``01:20:00``. - -This terminology differs from what Python's standard -[http://docs.python.org/library/datetime.html|datetime] module uses. -Basically its -[http://docs.python.org/library/datetime.html#datetime-objects|datetime] and -[http://docs.python.org/library/datetime.html#timedelta-objects|timedelta] -objects match ``date`` and ``time`` as defined by this library. - -= Date formats = - -Dates can given to and received from keywords in `timestamp`, `custom -timestamp`, `Python datetime` and `epoch time` formats. These formats are -discussed thoroughly in subsequent sections. - -Input format is determined automatically based on the given date except when -using custom timestamps, in which case it needs to be given using -``date_format`` argument. Default result format is timestamp, but it can -be overridden using ``result_format`` argument. - -== Timestamp == - -If a date is given as a string, it is always considered to be a timestamp. -If no custom formatting is given using ``date_format`` argument, the timestamp -is expected to be in [http://en.wikipedia.org/wiki/ISO_8601|ISO 8601] like -format ``YYYY-MM-DD hh:mm:ss.mil``, where any non-digit character can be used -as a separator or separators can be omitted altogether. Additionally, -only the date part is mandatory, all possibly missing time components are -considered to be zeros. - -Dates can also be returned in the same ``YYYY-MM-DD hh:mm:ss.mil`` format by -using ``timestamp`` value with ``result_format`` argument. This is also the -default format that keywords returning dates use. Milliseconds can be excluded -using ``exclude_millis`` as explained in `Millisecond handling` section. - -Examples: -| ${date1} = | Convert Date | 2014-06-11 10:07:42.000 | -| ${date2} = | Convert Date | 20140611 100742 | result_format=timestamp | -| Should Be Equal | ${date1} | ${date2} | -| ${date} = | Convert Date | 20140612 12:57 | exclude_millis=yes | -| Should Be Equal | ${date} | 2014-06-12 12:57:00 | - -== Custom timestamp == - -It is possible to use custom timestamps in both input and output. -The custom format is same as accepted by Python's -[http://docs.python.org/library/datetime.html#strftime-strptime-behavior| -datatime.strptime] function. For example, the default timestamp discussed -in the previous section would match ``%Y-%m-%d %H:%M:%S.%f``. - -When using a custom timestamp in input, it must be specified using -``date_format`` argument. The actual input value must be a string that matches -the specified format exactly. When using a custom timestamp in output, it must -be given using ``result_format`` argument. - -Examples: -| ${date} = | Convert Date | 28.05.2014 12:05 | date_format=%d.%m.%Y %H:%M | -| Should Be Equal | ${date} | 2014-05-28 12:05:00.000 | -| ${date} = | Convert Date | ${date} | result_format=%d.%m.%Y | -| Should Be Equal | ${date} | 28.05.2014 | - -Notice that locale aware directives like ``%b`` do not work correctly with -Jython on non-English locales: http://bugs.jython.org/issue2285 - -== Python datetime == - -Python's standard -[http://docs.python.org/library/datetime.html#datetime-objects|datetime] -objects can be used both in input and output. In input they are recognized -automatically, and in output it is possible to get them by giving ``datetime`` -value to ``result_format`` argument. - -One nice benefit with datetime objects is that they have different time -components available as attributes that can be easily accessed using the -extended variable syntax. - -Examples: -| ${datetime} = | Convert Date | 2014-06-11 10:07:42.123 | datetime | -| Should Be Equal As Integers | ${datetime.year} | 2014 | -| Should Be Equal As Integers | ${datetime.month} | 6 | -| Should Be Equal As Integers | ${datetime.day} | 11 | -| Should Be Equal As Integers | ${datetime.hour} | 10 | -| Should Be Equal As Integers | ${datetime.minute} | 7 | -| Should Be Equal As Integers | ${datetime.second} | 42 | -| Should Be Equal As Integers | ${datetime.microsecond} | 123000 | - -== Epoch time == - -Epoch time is the time in seconds since the -[http://en.wikipedia.org/wiki/Unix_time|UNIX epoch] i.e. 00:00:00.000 (UTC) -1 January 1970. To give a date in epoch time, it must be given as a number -(integer or float), not as a string. To return a date in epoch time, -it is possible to use ``epoch`` value with ``result_format`` argument. -Epoch time is returned as a floating point number. - -Notice that epoch time itself is independent on timezones and thus same -around the world at a certain time. What local time a certain epoch time -matches obviously then depends on the timezone. For example, examples below -were tested in Finland but verifications would fail on other timezones. - -Examples: -| ${date} = | Convert Date | ${1000000000} | -| Should Be Equal | ${date} | 2001-09-09 04:46:40.000 | -| ${date} = | Convert Date | 2014-06-12 13:27:59.279 | epoch | -| Should Be Equal | ${date} | ${1402568879.279} | - -== Earliest supported date == - -The earliest date that is supported depends on the date format and to some -extend on the platform: - -- Timestamps support year 1900 and above. -- Python datetime objects support year 1 and above. -- Epoch time supports 1970 and above on Windows with Python and IronPython. -- On other platforms epoch time supports 1900 and above or even earlier. - -Prior to Robot Framework 2.9.2, all formats had same limitation as epoch time -has nowadays. - -= Time formats = - -Similarly as dates, times can be given to and received from keywords in -various different formats. Supported formats are `number`, `time string` -(verbose and compact), `timer string` and `Python timedelta`. - -Input format for time is always determined automatically based on the input. -Result format is number by default, but it can be customised using -``result_format`` argument. - -== Number == - -Time given as a number is interpreted to be seconds. It can be given -either as an integer or a float, or it can be a string that can be converted -to a number. - -To return a time as a number, ``result_format`` argument must have value -``number``, which is also the default. Returned number is always a float. - -Examples: -| ${time} = | Convert Time | 3.14 | -| Should Be Equal | ${time} | ${3.14} | -| ${time} = | Convert Time | ${time} | result_format=number | -| Should Be Equal | ${time} | ${3.14} | - -== Time string == - -Time strings are strings in format like ``1 minute 42 seconds`` or ``1min 42s``. -The basic idea of this format is having first a number and then a text -specifying what time that number represents. Numbers can be either -integers or floating point numbers, the whole format is case and space -insensitive, and it is possible to add a minus prefix to specify negative -times. The available time specifiers are: - -- ``days``, ``day``, ``d`` -- ``hours``, ``hour``, ``h`` -- ``minutes``, ``minute``, ``mins``, ``min``, ``m`` -- ``seconds``, ``second``, ``secs``, ``sec``, ``s`` -- ``milliseconds``, ``millisecond``, ``millis``, ``ms`` - -When returning a time string, it is possible to select between ``verbose`` -and ``compact`` representations using ``result_format`` argument. The verbose -format uses long specifiers ``day``, ``hour``, ``minute``, ``second`` and -``millisecond``, and adds ``s`` at the end when needed. The compact format uses -shorter specifiers ``d``, ``h``, ``min``, ``s`` and ``ms``, and even drops -the space between the number and the specifier. - -Examples: -| ${time} = | Convert Time | 1 minute 42 seconds | -| Should Be Equal | ${time} | ${102} | -| ${time} = | Convert Time | 4200 | verbose | -| Should Be Equal | ${time} | 1 hour 10 minutes | -| ${time} = | Convert Time | - 1.5 hours | compact | -| Should Be Equal | ${time} | - 1h 30min | - -== Timer string == - -Timer string is a string given in timer like format ``hh:mm:ss.mil``. In this -format both hour and millisecond parts are optional, leading and trailing -zeros can be left out when they are not meaningful, and negative times can -be represented by adding a minus prefix. - -To return a time as timer string, ``result_format`` argument must be given -value ``timer``. Timer strings are by default returned in full ``hh:mm:ss.mil`` -format, but milliseconds can be excluded using ``exclude_millis`` as explained -in `Millisecond handling` section. - -Examples: -| ${time} = | Convert Time | 01:42 | -| Should Be Equal | ${time} | ${102} | -| ${time} = | Convert Time | 01:10:00.123 | -| Should Be Equal | ${time} | ${4200.123} | -| ${time} = | Convert Time | 102 | timer | -| Should Be Equal | ${time} | 00:01:42.000 | -| ${time} = | Convert Time | -101.567 | timer | exclude_millis=yes | -| Should Be Equal | ${time} | -00:01:42 | - -== Python timedelta == - -Python's standard -[http://docs.python.org/library/datetime.html#datetime.timedelta|timedelta] -objects are also supported both in input and in output. In input they are -recognized automatically, and in output it is possible to receive them by -giving ``timedelta`` value to ``result_format`` argument. - -Examples: -| ${timedelta} = | Convert Time | 01:10:02.123 | timedelta | -| Should Be Equal | ${timedelta.total_seconds()} | ${4202.123} | - -= Millisecond handling = - -This library handles dates and times internally using the precision of the -given input. With `timestamp`, `time string`, and `timer string` result -formats seconds are, however, rounded to millisecond accuracy. Milliseconds -may also be included even if there would be none. - -All keywords returning dates or times have an option to leave milliseconds out -by giving a true value to ``exclude_millis`` argument. If the argument is given -as a string, it is considered true unless it is empty or case-insensitively -equal to ``false``, ``none`` or ``no``. Other argument types are tested using -same [http://docs.python.org/library/stdtypes.html#truth|rules as in -Python]. Notice that prior to Robot Framework 2.9, all strings except -the empty string were considered true, and that considering ``none`` false is -new in Robot Framework 3.0.3. - -When milliseconds are excluded, seconds in returned dates and times are -rounded to the nearest full second. With `timestamp` and `timer string` -result formats, milliseconds will also be removed from the returned string -altogether. - -Examples: -| ${date} = | Convert Date | 2014-06-11 10:07:42 | -| Should Be Equal | ${date} | 2014-06-11 10:07:42.000 | -| ${date} = | Convert Date | 2014-06-11 10:07:42.500 | exclude_millis=yes | -| Should Be Equal | ${date} | 2014-06-11 10:07:43 | -| ${dt} = | Convert Date | 2014-06-11 10:07:42.500 | datetime | exclude_millis=yes | -| Should Be Equal | ${dt.second} | ${43} | -| Should Be Equal | ${dt.microsecond} | ${0} | -| ${time} = | Convert Time | 102 | timer | exclude_millis=false | -| Should Be Equal | ${time} | 00:01:42.000 | | -| ${time} = | Convert Time | 102.567 | timer | exclude_millis=true | -| Should Be Equal | ${time} | 00:01:43 | | - -= Programmatic usage = - -In addition to be used as normal library, this library is intended to -provide a stable API for other libraries to use if they want to support -same date and time formats as this library. All the provided keywords -are available as functions that can be easily imported: - -| from robot.libraries.DateTime import convert_time -| -| def example_keyword(timeout): -| seconds = convert_time(timeout) -| # ... - -Additionally helper classes ``Date`` and ``Time`` can be used directly: - -| from robot.libraries.DateTime import Date, Time -| -| def example_keyword(date, interval): -| date = Date(date).convert('datetime') -| interval = Time(interval).convert('number') -| # ... - - -date -time -result_format=timestamp -exclude_millis=False -date_format=None - -Adds time to date and returns the resulting date. - -Arguments: -- ``date:`` Date to add time to in one of the supported - `date formats`. -- ``time:`` Time that is added in one of the supported - `time formats`. -- ``result_format:`` Format of the returned date. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. -- ``date_format:`` Possible `custom timestamp` format of ``date``. - -Examples: -| ${date} = | Add Time To Date | 2014-05-28 12:05:03.111 | 7 days | -| Should Be Equal | ${date} | 2014-06-04 12:05:03.111 | | -| ${date} = | Add Time To Date | 2014-05-28 12:05:03.111 | 01:02:03:004 | -| Should Be Equal | ${date} | 2014-05-28 13:07:06.115 | - - - - - -time1 -time2 -result_format=number -exclude_millis=False - -Adds time to another time and returns the resulting time. - -Arguments: -- ``time1:`` First time in one of the supported `time formats`. -- ``time2:`` Second time in one of the supported `time formats`. -- ``result_format:`` Format of the returned time. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. - -Examples: -| ${time} = | Add Time To Time | 1 minute | 42 | -| Should Be Equal | ${time} | ${102} | -| ${time} = | Add Time To Time | 3 hours 5 minutes | 01:02:03 | timer | exclude_millis=yes | -| Should Be Equal | ${time} | 04:07:03 | - - - - - -date -result_format=timestamp -exclude_millis=False -date_format=None - -Converts between supported `date formats`. - -Arguments: -- ``date:`` Date in one of the supported `date formats`. -- ``result_format:`` Format of the returned date. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. -- ``date_format:`` Specifies possible `custom timestamp` format. - -Examples: -| ${date} = | Convert Date | 20140528 12:05:03.111 | -| Should Be Equal | ${date} | 2014-05-28 12:05:03.111 | -| ${date} = | Convert Date | ${date} | epoch | -| Should Be Equal | ${date} | ${1401267903.111} | -| ${date} = | Convert Date | 5.28.2014 12:05 | exclude_millis=yes | date_format=%m.%d.%Y %H:%M | -| Should Be Equal | ${date} | 2014-05-28 12:05:00 | - - - - - -time -result_format=number -exclude_millis=False - -Converts between supported `time formats`. - -Arguments: -- ``time:`` Time in one of the supported `time formats`. -- ``result_format:`` Format of the returned time. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. - -Examples: -| ${time} = | Convert Time | 10 seconds | -| Should Be Equal | ${time} | ${10} | -| ${time} = | Convert Time | 1:00:01 | verbose | -| Should Be Equal | ${time} | 1 hour 1 second | -| ${time} = | Convert Time | ${3661.5} | timer | exclude_milles=yes | -| Should Be Equal | ${time} | 01:01:02 | - - - - - -time_zone=local -increment=0 -result_format=timestamp -exclude_millis=False - -Returns current local or UTC time with an optional increment. - -Arguments: -- ``time_zone:`` Get the current time on this time zone. Currently only - ``local`` (default) and ``UTC`` are supported. -- ``increment:`` Optional time increment to add to the returned date in - one of the supported `time formats`. Can be negative. -- ``result_format:`` Format of the returned date (see `date formats`). -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. - -Examples: -| ${date} = | Get Current Date | -| Should Be Equal | ${date} | 2014-06-12 20:00:58.946 | -| ${date} = | Get Current Date | UTC | -| Should Be Equal | ${date} | 2014-06-12 17:00:58.946 | -| ${date} = | Get Current Date | increment=02:30:00 | -| Should Be Equal | ${date} | 2014-06-12 22:30:58.946 | -| ${date} = | Get Current Date | UTC | - 5 hours | -| Should Be Equal | ${date} | 2014-06-12 12:00:58.946 | -| ${date} = | Get Current Date | result_format=datetime | -| Should Be Equal | ${date.year} | ${2014} | -| Should Be Equal | ${date.month} | ${6} | - - - - - -date1 -date2 -result_format=number -exclude_millis=False -date1_format=None -date2_format=None - -Subtracts date from another date and returns time between. - -Arguments: -- ``date1:`` Date to subtract another date from in one of the - supported `date formats`. -- ``date2:`` Date that is subtracted in one of the supported - `date formats`. -- ``result_format:`` Format of the returned time (see `time formats`). -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. -- ``date1_format:`` Possible `custom timestamp` format of ``date1``. -- ``date2_format:`` Possible `custom timestamp` format of ``date2``. - - Examples: -| ${time} = | Subtract Date From Date | 2014-05-28 12:05:52 | 2014-05-28 12:05:10 | -| Should Be Equal | ${time} | ${42} | -| ${time} = | Subtract Date From Date | 2014-05-28 12:05:52 | 2014-05-27 12:05:10 | verbose | -| Should Be Equal | ${time} | 1 day 42 seconds | - - - - - -date -time -result_format=timestamp -exclude_millis=False -date_format=None - -Subtracts time from date and returns the resulting date. - -Arguments: -- ``date:`` Date to subtract time from in one of the supported - `date formats`. -- ``time:`` Time that is subtracted in one of the supported - `time formats`. -- ``result_format:`` Format of the returned date. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. -- ``date_format:`` Possible `custom timestamp` format of ``date``. - -Examples: -| ${date} = | Subtract Time From Date | 2014-06-04 12:05:03.111 | 7 days | -| Should Be Equal | ${date} | 2014-05-28 12:05:03.111 | -| ${date} = | Subtract Time From Date | 2014-05-28 13:07:06.115 | 01:02:03:004 | -| Should Be Equal | ${date} | 2014-05-28 12:05:03.111 | - - - - - -time1 -time2 -result_format=number -exclude_millis=False - -Subtracts time from another time and returns the resulting time. - -Arguments: -- ``time1:`` Time to subtract another time from in one of - the supported `time formats`. -- ``time2:`` Time to subtract in one of the supported `time formats`. -- ``result_format:`` Format of the returned time. -- ``exclude_millis:`` When set to any true value, rounds and drops - milliseconds as explained in `millisecond handling`. - -Examples: -| ${time} = | Subtract Time From Time | 00:02:30 | 100 | -| Should Be Equal | ${time} | ${50} | -| ${time} = | Subtract Time From Time | ${time} | 1 minute | compact | -| Should Be Equal | ${time} | - 10s | - - - - diff --git a/libspecs/Dialogs.libspec b/libspecs/Dialogs.libspec deleted file mode 100644 index 26f83b6..0000000 --- a/libspecs/Dialogs.libspec +++ /dev/null @@ -1,112 +0,0 @@ - - -3.1.2 -global -yes -A test library providing dialogs for interacting with users. - -``Dialogs`` is Robot Framework's standard library that provides means -for pausing the test execution and getting input from users. The -dialogs are slightly different depending on whether tests are run on -Python, IronPython or Jython but they provide the same functionality. - -Long lines in the provided messages are wrapped automatically. If you want -to wrap lines manually, you can add newlines using the ``\n`` character -sequence. - -The library has a known limitation that it cannot be used with timeouts -on Python. Support for IronPython was added in Robot Framework 2.9.2. - - -message -default_error= - -Pauses test execution until user sets the keyword status. - -User can press either ``PASS`` or ``FAIL`` button. In the latter case execution -fails and an additional dialog is opened for defining the error message. - -``message`` is the instruction shown in the initial dialog and -``default_error`` is the default value shown in the possible error message -dialog. - - - - - -message -*values - -Pauses test execution and asks user to select a value. - -The selected value is returned. Pressing ``Cancel`` fails the keyword. - -``message`` is the instruction shown in the dialog and ``values`` are -the options given to the user. - -Example: -| ${user} = | Get Selection From User | Select user | user1 | user2 | admin | - - - - - -message -*values - -Pauses test execution and asks user to select multiple values. - -The selected values are returned as a list. Selecting no values is OK -and in that case the returned list is empty. Pressing ``Cancel`` fails -the keyword. - -``message`` is the instruction shown in the dialog and ``values`` are -the options given to the user. - -Example: -| ${users} = | Get Selections From User | Select users | user1 | user2 | admin | - -New in Robot Framework 3.1. - - - - - -message -default_value= -hidden=False - -Pauses test execution and asks user to input a value. - -Value typed by the user, or the possible default value, is returned. -Returning an empty value is fine, but pressing ``Cancel`` fails the keyword. - -``message`` is the instruction shown in the dialog and ``default_value`` is -the possible default value shown in the input field. - -If ``hidden`` is given a true value, the value typed by the user is hidden. -``hidden`` is considered true if it is a non-empty string not equal to -``false``, ``none`` or ``no``, case-insensitively. If it is not a string, -its truth value is got directly using same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -Example: -| ${username} = | Get Value From User | Input user name | default | -| ${password} = | Get Value From User | Input password | hidden=yes | - -Considering strings ``false`` and ``no`` to be false is new in RF 2.9 -and considering string ``none`` false is new in RF 3.0.3. - - - - - -message=Test execution paused. Press OK to continue. - -Pauses test execution until user clicks ``Ok`` button. - -``message`` is the message shown in the dialog. - - - - diff --git a/libspecs/Easter.libspec b/libspecs/Easter.libspec deleted file mode 100644 index 62dcc47..0000000 --- a/libspecs/Easter.libspec +++ /dev/null @@ -1,15 +0,0 @@ - - - -global -yes -Documentation for library ``Easter``. - - -who - - - - - - diff --git a/libspecs/OperatingSystem.libspec b/libspecs/OperatingSystem.libspec deleted file mode 100644 index 81ef82f..0000000 --- a/libspecs/OperatingSystem.libspec +++ /dev/null @@ -1,1150 +0,0 @@ - - -3.1.2 -global -yes -A test library providing keywords for OS related tasks. - -``OperatingSystem`` is Robot Framework's standard library that -enables various operating system related tasks to be performed in -the system where Robot Framework is running. It can, among other -things, execute commands (e.g. `Run`), create and remove files and -directories (e.g. `Create File`, `Remove Directory`), check -whether files or directories exists or contain something -(e.g. `File Should Exist`, `Directory Should Be Empty`) and -manipulate environment variables (e.g. `Set Environment Variable`). - -== Table of contents == - -- `Path separators` -- `Pattern matching` -- `Tilde expansion` -- `Boolean arguments` -- `Example` -- `Shortcuts` -- `Keywords` - -= Path separators = - -Because Robot Framework uses the backslash (``\``) as an escape character -in the test data, using a literal backslash requires duplicating it like -in ``c:\\path\\file.txt``. That can be inconvenient especially with -longer Windows paths, and thus all keywords expecting paths as arguments -convert forward slashes to backslashes automatically on Windows. This also -means that paths like ``${CURDIR}/path/file.txt`` are operating system -independent. - -Notice that the automatic path separator conversion does not work if -the path is only a part of an argument like with `Run` and `Start Process` -keywords. In these cases the built-in variable ``${/}`` that contains -``\`` or ``/``, depending on the operating system, can be used instead. - -= Pattern matching = - -Some keywords allow their arguments to be specified as -[http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where: - -| ``*`` | matches any string, even an empty string | -| ``?`` | matches any single character | -| ``[chars]`` | matches one character in the bracket | -| ``[!chars]`` | matches one character not in the bracket | -| ``[a-z]`` | matches one character from the range in the bracket | -| ``[!a-z]`` | matches one character not from the range in the bracket | - -Unless otherwise noted, matching is case-insensitive on -case-insensitive operating systems such as Windows. - -Starting from Robot Framework 2.9.1, globbing is not done if the given path -matches an existing file even if it would contain a glob pattern. - -= Tilde expansion = - -Paths beginning with ``~`` or ``~username`` are expanded to the current or -specified user's home directory, respectively. The resulting path is -operating system dependent, but typically e.g. ``~/robot`` is expanded to -``C:\Users\<user>\robot`` on Windows and ``/home/<user>/robot`` on -Unixes. - -The ``~username`` form does not work on Jython. - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Other strings are considered true regardless -their value, and other argument types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Remove Directory` | ${path} | recursive=True | # Strings are generally true. | -| `Remove Directory` | ${path} | recursive=yes | # Same as the above. | -| `Remove Directory` | ${path} | recursive=${TRUE} | # Python ``True`` is true. | -| `Remove Directory` | ${path} | recursive=${42} | # Numbers other than 0 are true. | - -False examples: -| `Remove Directory` | ${path} | recursive=False | # String ``false`` is false. | -| `Remove Directory` | ${path} | recursive=no | # Also string ``no`` is false. | -| `Remove Directory` | ${path} | recursive=${EMPTY} | # Empty string is false. | -| `Remove Directory` | ${path} | recursive=${FALSE} | # Python ``False`` is false. | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - -= Example = - -| =Setting= | =Value= | -| Library | OperatingSystem | - -| =Variable= | =Value= | -| ${PATH} | ${CURDIR}/example.txt | - -| =Test Case= | =Action= | =Argument= | =Argument= | -| Example | Create File | ${PATH} | Some text | -| | File Should Exist | ${PATH} | | -| | Copy File | ${PATH} | ~/file.txt | -| | ${output} = | Run | ${TEMPDIR}${/}script.py arg | - - -name -*values -**config - -Appends given ``values`` to environment variable ``name``. - -If the environment variable already exists, values are added after it, -and otherwise a new environment variable is created. - -Values are, by default, joined together using the operating system -path separator (``;`` on Windows, ``:`` elsewhere). This can be changed -by giving a separator after the values like ``separator=value``. No -other configuration parameters are accepted. - -Examples (assuming ``NAME`` and ``NAME2`` do not exist initially): -| Append To Environment Variable | NAME | first | | -| Should Be Equal | %{NAME} | first | | -| Append To Environment Variable | NAME | second | third | -| Should Be Equal | %{NAME} | first${:}second${:}third | -| Append To Environment Variable | NAME2 | first | separator=- | -| Should Be Equal | %{NAME2} | first | | -| Append To Environment Variable | NAME2 | second | separator=- | -| Should Be Equal | %{NAME2} | first-second | - - - - - -path -content -encoding=UTF-8 - -Appends the given content to the specified file. - -If the file exists, the given text is written to its end. If the file -does not exist, it is created. - -Other than not overwriting possible existing files, this keyword works -exactly like `Create File`. See its documentation for more details -about the usage. - -Note that special encodings ``SYSTEM`` and ``CONSOLE`` only work -with this keyword starting from Robot Framework 3.1.2. - - - - - -source -destination - -Copies the source directory into the destination. - -If the destination exists, the source is copied under it. Otherwise -the destination directory and the possible missing intermediate -directories are created. - - - - - -source -destination - -Copies the source file into the destination. - -Source must be a path to an existing file or a glob pattern (see -`Pattern matching`) that matches exactly one file. How the -destination is interpreted is explained below. - -1) If the destination is an existing file, the source file is copied -over it. - -2) If the destination is an existing directory, the source file is -copied into it. A possible file with the same name as the source is -overwritten. - -3) If the destination does not exist and it ends with a path -separator (``/`` or ``\``), it is considered a directory. That -directory is created and a source file copied into it. -Possible missing intermediate directories are also created. - -4) If the destination does not exist and it does not end with a path -separator, it is considered a file. If the path to the file does not -exist, it is created. - -The resulting destination path is returned since Robot Framework 2.9.2. - -See also `Copy Files`, `Move File`, and `Move Files`. - - - - - -*sources_and_destination - -Copies specified files to the target directory. - -Source files can be given as exact paths and as glob patterns (see -`Pattern matching`). At least one source must be given, but it is -not an error if it is a pattern that does not match anything. - -Last argument must be the destination directory. If the destination -does not exist, it will be created. - -Examples: -| Copy Files | ${dir}/file1.txt | ${dir}/file2.txt | ${dir2} | -| Copy Files | ${dir}/file-*.txt | ${dir2} | | - -See also `Copy File`, `Move File`, and `Move Files`. - - - - - -path -pattern=None - -Wrapper for `Count Items In Directory` returning only directory count. - - - - - -path -pattern=None - -Wrapper for `Count Items In Directory` returning only file count. - - - - - -path -pattern=None - -Returns and logs the number of all items in the given directory. - -The argument ``pattern`` has the same semantics as with `List Directory` -keyword. The count is returned as an integer, so it must be checked e.g. -with the built-in keyword `Should Be Equal As Integers`. - - - - - -path -content - -Creates a binary file with the given content. - -If content is given as a Unicode string, it is first converted to bytes -character by character. All characters with ordinal below 256 can be -used and are converted to bytes with same values. Using characters -with higher ordinal is an error. - -Byte strings, and possible other types, are written to the file as is. - -If the directory for the file does not exist, it is created, along -with missing intermediate directories. - -Examples: -| Create Binary File | ${dir}/example.png | ${image content} | -| Create Binary File | ${path} | \x01\x00\xe4\x00 | - -Use `Create File` if you want to create a text file using a certain -encoding. `File Should Not Exist` can be used to avoid overwriting -existing files. - - - - - -path - -Creates the specified directory. - -Also possible intermediate directories are created. Passes if the -directory already exists, but fails if the path exists and is not -a directory. - - - - - -path -content= -encoding=UTF-8 - -Creates a file with the given content and encoding. - -If the directory where the file is created does not exist, it is -automatically created along with possible missing intermediate -directories. Possible existing file is overwritten. - -On Windows newline characters (``\n``) in content are automatically -converted to Windows native newline sequence (``\r\n``). - -See `Get File` for more information about possible ``encoding`` values, -including special values ``SYSTEM`` and ``CONSOLE``. - -Examples: -| Create File | ${dir}/example.txt | Hello, world! | | -| Create File | ${path} | Hyv\xe4 esimerkki | Latin-1 | -| Create File | /tmp/foo.txt | 3\nlines\nhere\n | SYSTEM | - -Use `Append To File` if you want to append to an existing file -and `Create Binary File` if you need to write bytes without encoding. -`File Should Not Exist` can be used to avoid overwriting existing -files. - -The support for ``SYSTEM`` and ``CONSOLE`` encodings is new in Robot -Framework 3.0. Automatically converting ``\n`` to ``\r\n`` on -Windows is new in Robot Framework 3.1. - - - - - -path -msg=None - -Fails unless the specified directory is empty. - -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails unless the given path points to an existing directory. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails if the specified directory is empty. - -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails if the given path points to an existing file. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path - -Deletes all the content from the given directory. - -Deletes both files and sub-directories, but the specified directory -itself if not removed. Use `Remove Directory` if you want to remove -the whole directory. - - - - - -name -msg=None - -Fails if the specified environment variable is not set. - -The default error message can be overridden with the ``msg`` argument. - - - - - -name -msg=None - -Fails if the specified environment variable is set. - -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails unless the specified file is empty. - -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails unless the given ``path`` points to an existing file. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails if the specified directory is empty. - -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails if the given path points to an existing file. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path - -Returns the contents of a specified file. - -This keyword reads the specified file and returns the contents as is. -See also `Get File`. - - - - - -name -default=None - -Returns the value of an environment variable with the given name. - -If no such environment variable is set, returns the default value, if -given. Otherwise fails the test case. - -Returned variables are automatically decoded to Unicode using -the system encoding. - -Note that you can also access environment variables directly using -the variable syntax ``%{ENV_VAR_NAME}``. - - - - - - -Returns currently available environment variables as a dictionary. - -Both keys and values are decoded to Unicode using the system encoding. -Altering the returned dictionary has no effect on the actual environment -variables. - - - - - -path -encoding=UTF-8 -encoding_errors=strict - -Returns the contents of a specified file. - -This keyword reads the specified file and returns the contents. -Line breaks in content are converted to platform independent form. -See also `Get Binary File`. - -``encoding`` defines the encoding of the file. The default value is -``UTF-8``, which means that UTF-8 and ASCII encoded files are read -correctly. In addition to the encodings supported by the underlying -Python implementation, the following special encoding values can be -used: - -- ``SYSTEM``: Use the default system encoding. -- ``CONSOLE``: Use the console encoding. Outside Windows this is same - as the system encoding. - -``encoding_errors`` argument controls what to do if decoding some bytes -fails. All values accepted by ``decode`` method in Python are valid, but -in practice the following values are most useful: - -- ``strict``: Fail if characters cannot be decoded (default). -- ``ignore``: Ignore characters that cannot be decoded. -- ``replace``: Replace characters that cannot be decoded with - a replacement character. - -Support for ``SYSTEM`` and ``CONSOLE`` encodings in Robot Framework 3.0. - - - - - -path - -Returns and logs file size as an integer in bytes. - - - - - -path -format=timestamp - -Returns the last modification time of a file or directory. - -How time is returned is determined based on the given ``format`` -string as follows. Note that all checks are case-insensitive. -Returned time is also automatically logged. - -1) If ``format`` contains the word ``epoch``, the time is returned - in seconds after the UNIX epoch. The return value is always - an integer. - -2) If ``format`` contains any of the words ``year``, ``month``, - ``day``, ``hour``, ``min`` or ``sec``, only the selected parts are - returned. The order of the returned parts is always the one - in the previous sentence and the order of the words in - ``format`` is not significant. The parts are returned as - zero-padded strings (e.g. May -> ``05``). - -3) Otherwise, and by default, the time is returned as a - timestamp string in the format ``2006-02-24 15:08:31``. - -Examples (when the modified time of ``${CURDIR}`` is -2006-03-29 15:06:21): -| ${time} = | Get Modified Time | ${CURDIR} | -| ${secs} = | Get Modified Time | ${CURDIR} | epoch | -| ${year} = | Get Modified Time | ${CURDIR} | return year | -| ${y} | ${d} = | Get Modified Time | ${CURDIR} | year,day | -| @{time} = | Get Modified Time | ${CURDIR} | year,month,day,hour,min,sec | -=> -- ${time} = '2006-03-29 15:06:21' -- ${secs} = 1143637581 -- ${year} = '2006' -- ${y} = '2006' & ${d} = '29' -- @{time} = ['2006', '03', '29', '15', '06', '21'] - - - - - -path -pattern -encoding=UTF-8 -encoding_errors=strict - -Returns the lines of the specified file that match the ``pattern``. - -This keyword reads a file from the file system using the defined -``path``, ``encoding`` and ``encoding_errors`` similarly as `Get File`. -A difference is that only the lines that match the given ``pattern`` are -returned. Lines are returned as a single string catenated back together -with newlines and the number of matched lines is automatically logged. -Possible trailing newline is never returned. - -A line matches if it contains the ``pattern`` anywhere in it and -it *does not need to match the pattern fully*. The pattern -matching syntax is explained in `introduction`, and in this -case matching is case-sensitive. - -Examples: -| ${errors} = | Grep File | /var/log/myapp.log | ERROR | -| ${ret} = | Grep File | ${CURDIR}/file.txt | [Ww]ildc??d ex*ple | - -If more complex pattern matching is needed, it is possible to use -`Get File` in combination with String library keywords like `Get -Lines Matching Regexp`. - - - - - -base -*parts - -Joins the given path part(s) to the given base path. - -The path separator (``/`` or ``\``) is inserted when needed and -the possible absolute paths handled as expected. The resulted -path is also normalized. - -Examples: -| ${path} = | Join Path | my | path | -| ${p2} = | Join Path | my/ | path/ | -| ${p3} = | Join Path | my | path | my | file.txt | -| ${p4} = | Join Path | my | /path | -| ${p5} = | Join Path | /my/path/ | .. | path2 | -=> -- ${path} = 'my/path' -- ${p2} = 'my/path' -- ${p3} = 'my/path/my/file.txt' -- ${p4} = '/path' -- ${p5} = '/my/path2' - - - - - -base -*paths - -Joins given paths with base and returns resulted paths. - -See `Join Path` for more information. - -Examples: -| @{p1} = | Join Paths | base | example | other | | -| @{p2} = | Join Paths | /my/base | /example | other | | -| @{p3} = | Join Paths | my/base | example/path/ | other | one/more | -=> -- @{p1} = ['base/example', 'base/other'] -- @{p2} = ['/example', '/my/base/other'] -- @{p3} = ['my/base/example/path', 'my/base/other', 'my/base/one/more'] - - - - - -path -pattern=None -absolute=False - -Wrapper for `List Directory` that returns only directories. - - - - - -path -pattern=None -absolute=False - -Returns and logs items in a directory, optionally filtered with ``pattern``. - -File and directory names are returned in case-sensitive alphabetical -order, e.g. ``['A Name', 'Second', 'a lower case name', 'one more']``. -Implicit directories ``.`` and ``..`` are not returned. The returned -items are automatically logged. - -File and directory names are returned relative to the given path -(e.g. ``'file.txt'``) by default. If you want them be returned in -absolute format (e.g. ``'/home/robot/file.txt'``), give the ``absolute`` -argument a true value (see `Boolean arguments`). - -If ``pattern`` is given, only items matching it are returned. The pattern -matching syntax is explained in `introduction`, and in this case -matching is case-sensitive. - -Examples (using also other `List Directory` variants): -| @{items} = | List Directory | ${TEMPDIR} | -| @{files} = | List Files In Directory | /tmp | *.txt | absolute | -| ${count} = | Count Files In Directory | ${CURDIR} | ??? | - - - - - -path -pattern=None -absolute=False - -Wrapper for `List Directory` that returns only files. - - - - - -level=INFO - -Logs all environment variables using the given log level. - -Environment variables are also returned the same way as with -`Get Environment Variables` keyword. - - - - - -path -encoding=UTF-8 -encoding_errors=strict - -Wrapper for `Get File` that also logs the returned file. - -The file is logged with the INFO level. If you want something else, -just use `Get File` and the built-in keyword `Log` with the desired -level. - -See `Get File` for more information about ``encoding`` and -``encoding_errors`` arguments. - - - - - -source -destination - -Moves the source directory into a destination. - -Uses `Copy Directory` keyword internally, and ``source`` and -``destination`` arguments have exactly same semantics as with -that keyword. - - - - - -source -destination - -Moves the source file into the destination. - -Arguments have exactly same semantics as with `Copy File` keyword. -Destination file path is returned since Robot Framework 2.9.2. - -If the source and destination are on the same filesystem, rename -operation is used. Otherwise file is copied to the destination -filesystem and then removed from the original filesystem. - -See also `Move Files`, `Copy File`, and `Copy Files`. - - - - - -*sources_and_destination - -Moves specified files to the target directory. - -Arguments have exactly same semantics as with `Copy Files` keyword. - -See also `Move File`, `Copy File`, and `Copy Files`. - - - - - -path -case_normalize=False - -Normalizes the given path. - -- Collapses redundant separators and up-level references. -- Converts ``/`` to ``\`` on Windows. -- Replaces initial ``~`` or ``~user`` by that user's home directory. - The latter is not supported on Jython. -- If ``case_normalize`` is given a true value (see `Boolean arguments`) - on Windows, converts the path to all lowercase. New in Robot - Framework 3.1. - -Examples: -| ${path1} = | Normalize Path | abc/ | -| ${path2} = | Normalize Path | abc/../def | -| ${path3} = | Normalize Path | abc/./def//ghi | -| ${path4} = | Normalize Path | ~robot/stuff | -=> -- ${path1} = 'abc' -- ${path2} = 'def' -- ${path3} = 'abc/def/ghi' -- ${path4} = '/home/robot/stuff' - -On Windows result would use ``\`` instead of ``/`` and home directory -would be different. - - - - - -path -recursive=False - -Removes the directory pointed to by the given ``path``. - -If the second argument ``recursive`` is given a true value (see -`Boolean arguments`), the directory is removed recursively. Otherwise -removing fails if the directory is not empty. - -If the directory pointed to by the ``path`` does not exist, the keyword -passes, but it fails, if the ``path`` points to a file. - - - - - -*names - -Deletes the specified environment variable. - -Does nothing if the environment variable is not set. - -It is possible to remove multiple variables by passing them to this -keyword as separate arguments. - - - - - -path - -Removes a file with the given path. - -Passes if the file does not exist, but fails if the path does -not point to a regular file (e.g. it points to a directory). - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -If the path is a pattern, all files matching it are removed. - - - - - -*paths - -Uses `Remove File` to remove multiple files one-by-one. - -Example: -| Remove Files | ${TEMPDIR}${/}foo.txt | ${TEMPDIR}${/}bar.txt | ${TEMPDIR}${/}zap.txt | - - - - - -command - -Runs the given command in the system and returns the output. - -The execution status of the command *is not checked* by this -keyword, and it must be done separately based on the returned -output. If the execution return code is needed, either `Run -And Return RC` or `Run And Return RC And Output` can be used. - -The standard error stream is automatically redirected to the standard -output stream by adding ``2>&1`` after the executed command. This -automatic redirection is done only when the executed command does not -contain additional output redirections. You can thus freely forward -the standard error somewhere else, for example, like -``my_command 2>stderr.txt``. - -The returned output contains everything written into the standard -output or error streams by the command (unless either of them -is redirected explicitly). Many commands add an extra newline -(``\n``) after the output to make it easier to read in the -console. To ease processing the returned output, this possible -trailing newline is stripped by this keyword. - -Examples: -| ${output} = | Run | ls -lhF /tmp | -| Log | ${output} | -| ${result} = | Run | ${CURDIR}${/}tester.py arg1 arg2 | -| Should Not Contain | ${result} | FAIL | -| ${stdout} = | Run | /opt/script.sh 2>/tmp/stderr.txt | -| Should Be Equal | ${stdout} | TEST PASSED | -| File Should Be Empty | /tmp/stderr.txt | - -*TIP:* `Run Process` keyword provided by the -[http://robotframework.org/robotframework/latest/libraries/Process.html| -Process library] supports better process configuration and is generally -recommended as a replacement for this keyword. - - - - - -command - -Runs the given command in the system and returns the return code. - -The return code (RC) is returned as a positive integer in -range from 0 to 255 as returned by the executed command. On -some operating systems (notable Windows) original return codes -can be something else, but this keyword always maps them to -the 0-255 range. Since the RC is an integer, it must be -checked e.g. with the keyword `Should Be Equal As Integers` -instead of `Should Be Equal` (both are built-in keywords). - -Examples: -| ${rc} = | Run and Return RC | ${CURDIR}${/}script.py arg | -| Should Be Equal As Integers | ${rc} | 0 | -| ${rc} = | Run and Return RC | /path/to/example.rb arg1 arg2 | -| Should Be True | 0 < ${rc} < 42 | - -See `Run` and `Run And Return RC And Output` if you need to get the -output of the executed command. - -*TIP:* `Run Process` keyword provided by the -[http://robotframework.org/robotframework/latest/libraries/Process.html| -Process library] supports better process configuration and is generally -recommended as a replacement for this keyword. - - - - - -command - -Runs the given command in the system and returns the RC and output. - -The return code (RC) is returned similarly as with `Run And Return RC` -and the output similarly as with `Run`. - -Examples: -| ${rc} | ${output} = | Run and Return RC and Output | ${CURDIR}${/}mytool | -| Should Be Equal As Integers | ${rc} | 0 | -| Should Not Contain | ${output} | FAIL | -| ${rc} | ${stdout} = | Run and Return RC and Output | /opt/script.sh 2>/tmp/stderr.txt | -| Should Be True | ${rc} > 42 | -| Should Be Equal | ${stdout} | TEST PASSED | -| File Should Be Empty | /tmp/stderr.txt | - -*TIP:* `Run Process` keyword provided by the -[http://robotframework.org/robotframework/latest/libraries/Process.html| -Process library] supports better process configuration and is generally -recommended as a replacement for this keyword. - - - - - -name -value - -Sets an environment variable to a specified value. - -Values are converted to strings automatically. Set variables are -automatically encoded using the system encoding. - - - - - -path -mtime - -Sets the file modification and access times. - -Changes the modification and access times of the given file to -the value determined by ``mtime``. The time can be given in -different formats described below. Note that all checks -involving strings are case-insensitive. Modified time can only -be set to regular files. - -1) If ``mtime`` is a number, or a string that can be converted - to a number, it is interpreted as seconds since the UNIX - epoch (1970-01-01 00:00:00 UTC). This documentation was - originally written about 1177654467 seconds after the epoch. - -2) If ``mtime`` is a timestamp, that time will be used. Valid - timestamp formats are ``YYYY-MM-DD hh:mm:ss`` and - ``YYYYMMDD hhmmss``. - -3) If ``mtime`` is equal to ``NOW``, the current local time is used. - -4) If ``mtime`` is equal to ``UTC``, the current time in - [http://en.wikipedia.org/wiki/Coordinated_Universal_Time|UTC] - is used. - -5) If ``mtime`` is in the format like ``NOW - 1 day`` or ``UTC + 1 - hour 30 min``, the current local/UTC time plus/minus the time - specified with the time string is used. The time string format - is described in an appendix of Robot Framework User Guide. - -Examples: -| Set Modified Time | /path/file | 1177654467 | # Time given as epoch seconds | -| Set Modified Time | /path/file | 2007-04-27 9:14:27 | # Time given as a timestamp | -| Set Modified Time | /path/file | NOW | # The local time of execution | -| Set Modified Time | /path/file | NOW - 1 day | # 1 day subtracted from the local time | -| Set Modified Time | /path/file | UTC + 1h 2min 3s | # 1h 2min 3s added to the UTC time | - - - - - -path -msg=None - -Fails unless the given path (file or directory) exists. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path -msg=None - -Fails if the given path (file or directory) exists. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -The default error message can be overridden with the ``msg`` argument. - - - - - -path - -Splits the extension from the given path. - -The given path is first normalized (e.g. possible trailing -path separators removed, special directories ``..`` and ``.`` -removed). The base path and extension are returned as separate -components so that the dot used as an extension separator is -removed. If the path contains no extension, an empty string is -returned for it. Possible leading and trailing dots in the file -name are never considered to be extension separators. - -Examples: -| ${path} | ${ext} = | Split Extension | file.extension | -| ${p2} | ${e2} = | Split Extension | path/file.ext | -| ${p3} | ${e3} = | Split Extension | path/file | -| ${p4} | ${e4} = | Split Extension | p1/../p2/file.ext | -| ${p5} | ${e5} = | Split Extension | path/.file.ext | -| ${p6} | ${e6} = | Split Extension | path/.file | -=> -- ${path} = 'file' & ${ext} = 'extension' -- ${p2} = 'path/file' & ${e2} = 'ext' -- ${p3} = 'path/file' & ${e3} = '' -- ${p4} = 'p2/file' & ${e4} = 'ext' -- ${p5} = 'path/.file' & ${e5} = 'ext' -- ${p6} = 'path/.file' & ${e6} = '' - - - - - -path - -Splits the given path from the last path separator (``/`` or ``\``). - -The given path is first normalized (e.g. a possible trailing -path separator is removed, special directories ``..`` and ``.`` -removed). The parts that are split are returned as separate -components. - -Examples: -| ${path1} | ${dir} = | Split Path | abc/def | -| ${path2} | ${file} = | Split Path | abc/def/ghi.txt | -| ${path3} | ${d2} = | Split Path | abc/../def/ghi/ | -=> -- ${path1} = 'abc' & ${dir} = 'def' -- ${path2} = 'abc/def' & ${file} = 'ghi.txt' -- ${path3} = 'def' & ${d2} = 'ghi' - - - - - -path - -Emulates the UNIX touch command. - -Creates a file, if it does not exist. Otherwise changes its access and -modification times to the current time. - -Fails if used with the directories or the parent directory of the given -file does not exist. - - - - - -path -timeout=1 minute - -Waits until the given file or directory is created. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -If the path is a pattern, the keyword returns when an item matching -it is created. - -The optional ``timeout`` can be used to control the maximum time of -waiting. The timeout is given as a timeout string, e.g. in a format -``15 seconds``, ``1min 10s`` or just ``10``. The time string format is -described in an appendix of Robot Framework User Guide. - -If the timeout is negative, the keyword is never timed-out. The keyword -returns immediately, if the path already exists. - - - - - -path -timeout=1 minute - -Waits until the given file or directory is removed. - -The path can be given as an exact path or as a glob pattern. -The pattern matching syntax is explained in `introduction`. -If the path is a pattern, the keyword waits until all matching -items are removed. - -The optional ``timeout`` can be used to control the maximum time of -waiting. The timeout is given as a timeout string, e.g. in a format -``15 seconds``, ``1min 10s`` or just ``10``. The time string format is -described in an appendix of Robot Framework User Guide. - -If the timeout is negative, the keyword is never timed-out. The keyword -returns immediately, if the path does not exist in the first place. - - - - diff --git a/libspecs/Process.libspec b/libspecs/Process.libspec deleted file mode 100644 index 2bedb8f..0000000 --- a/libspecs/Process.libspec +++ /dev/null @@ -1,637 +0,0 @@ - - -3.1.2 -global -yes -Robot Framework test library for running processes. - -This library utilizes Python's -[http://docs.python.org/library/subprocess.html|subprocess] -module and its -[http://docs.python.org/library/subprocess.html#popen-constructor|Popen] -class. - -The library has following main usages: - -- Running processes in system and waiting for their completion using - `Run Process` keyword. -- Starting processes on background using `Start Process`. -- Waiting started process to complete using `Wait For Process` or - stopping them with `Terminate Process` or `Terminate All Processes`. - -== Table of contents == - -- `Specifying command and arguments` -- `Process configuration` -- `Active process` -- `Result object` -- `Boolean arguments` -- `Example` -- `Shortcuts` -- `Keywords` - -= Specifying command and arguments = - -Both `Run Process` and `Start Process` accept the command to execute and -all arguments passed to the command as separate arguments. This makes usage -convenient and also allows these keywords to automatically escape possible -spaces and other special characters in commands and arguments. Notice that -if a command accepts options that themselves accept values, these options -and their values must be given as separate arguments. - -When `running processes in shell`, it is also possible to give the whole -command to execute as a single string. The command can then contain -multiple commands to be run together. When using this approach, the caller -is responsible on escaping. - -Examples: -| `Run Process` | ${tools}${/}prog.py | argument | second arg with spaces | -| `Run Process` | java | -jar | ${jars}${/}example.jar | --option | value | -| `Run Process` | prog.py "one arg" && tool.sh | shell=yes | cwd=${tools} | - -Possible non-string arguments are converted to strings automatically. - -= Process configuration = - -`Run Process` and `Start Process` keywords can be configured using -optional ``**configuration`` keyword arguments. Configuration arguments -must be given after other arguments passed to these keywords and must -use syntax like ``name=value``. Available configuration arguments are -listed below and discussed further in sections afterwards. - -| = Name = | = Explanation = | -| shell | Specifies whether to run the command in shell or not. | -| cwd | Specifies the working directory. | -| env | Specifies environment variables given to the process. | -| env:<name> | Overrides the named environment variable(s) only. | -| stdout | Path of a file where to write standard output. | -| stderr | Path of a file where to write standard error. | -| output_encoding | Encoding to use when reading command outputs. | -| alias | Alias given to the process. | - -Note that because ``**configuration`` is passed using ``name=value`` syntax, -possible equal signs in other arguments passed to `Run Process` and -`Start Process` must be escaped with a backslash like ``name\=value``. -See `Run Process` for an example. - -== Running processes in shell == - -The ``shell`` argument specifies whether to run the process in a shell or -not. By default shell is not used, which means that shell specific commands, -like ``copy`` and ``dir`` on Windows, are not available. You can, however, -run shell scripts and batch files without using a shell. - -Giving the ``shell`` argument any non-false value, such as ``shell=True``, -changes the program to be executed in a shell. It allows using the shell -capabilities, but can also make the process invocation operating system -dependent. Having a shell between the actually started process and this -library can also interfere communication with the process such as stopping -it and reading its outputs. Because of these problems, it is recommended -to use the shell only when absolutely necessary. - -When using a shell it is possible to give the whole command to execute -as a single string. See `Specifying command and arguments` section for -examples and more details in general. - -== Current working directory == - -By default the child process will be executed in the same directory -as the parent process, the process running tests, is executed. This -can be changed by giving an alternative location using the ``cwd`` argument. -Forward slashes in the given path are automatically converted to -backslashes on Windows. - -`Standard output and error streams`, when redirected to files, -are also relative to the current working directory possibly set using -the ``cwd`` argument. - -Example: -| `Run Process` | prog.exe | cwd=${ROOT}/directory | stdout=stdout.txt | - -== Environment variables == - -By default the child process will get a copy of the parent process's -environment variables. The ``env`` argument can be used to give the -child a custom environment as a Python dictionary. If there is a need -to specify only certain environment variable, it is possible to use the -``env:<name>=<value>`` format to set or override only that named variables. -It is also possible to use these two approaches together. - -Examples: -| `Run Process` | program | env=${environ} | -| `Run Process` | program | env:http_proxy=10.144.1.10:8080 | env:PATH=%{PATH}${:}${PROGDIR} | -| `Run Process` | program | env=${environ} | env:EXTRA=value | - -== Standard output and error streams == - -By default processes are run so that their standard output and standard -error streams are kept in the memory. This works fine normally, -but if there is a lot of output, the output buffers may get full and -the program can hang. Additionally on Jython, everything written to -these in-memory buffers can be lost if the process is terminated. - -To avoid the above mentioned problems, it is possible to use ``stdout`` -and ``stderr`` arguments to specify files on the file system where to -redirect the outputs. This can also be useful if other processes or -other keywords need to read or manipulate the outputs somehow. - -Given ``stdout`` and ``stderr`` paths are relative to the `current working -directory`. Forward slashes in the given paths are automatically converted -to backslashes on Windows. - -As a special feature, it is possible to redirect the standard error to -the standard output by using ``stderr=STDOUT``. - -Regardless are outputs redirected to files or not, they are accessible -through the `result object` returned when the process ends. Commands are -expected to write outputs using the console encoding, but `output encoding` -can be configured using the ``output_encoding`` argument if needed. - -Examples: -| ${result} = | `Run Process` | program | stdout=${TEMPDIR}/stdout.txt | stderr=${TEMPDIR}/stderr.txt | -| `Log Many` | stdout: ${result.stdout} | stderr: ${result.stderr} | -| ${result} = | `Run Process` | program | stderr=STDOUT | -| `Log` | all output: ${result.stdout} | - -Note that the created output files are not automatically removed after -the test run. The user is responsible to remove them if needed. - -== Output encoding == - -Executed commands are, by default, expected to write outputs to the -`standard output and error streams` using the encoding used by the -system console. If the command uses some other encoding, that can be -configured using the ``output_encoding`` argument. This is especially -useful on Windows where the console uses a different encoding than rest -of the system, and many commands use the general system encoding instead -of the console encoding. - -The value used with the ``output_encoding`` argument must be a valid -encoding and must match the encoding actually used by the command. As a -convenience, it is possible to use strings ``CONSOLE`` and ``SYSTEM`` -to specify that the console or system encoding is used, respectively. -If produced outputs use different encoding then configured, values got -through the `result object` will be invalid. - -Examples: -| `Start Process` | program | output_encoding=UTF-8 | -| `Run Process` | program | stdout=${path} | output_encoding=SYSTEM | - -The support to set output encoding is new in Robot Framework 3.0. - -== Alias == - -A custom name given to the process that can be used when selecting the -`active process`. - -Examples: -| `Start Process` | program | alias=example | -| `Run Process` | python | -c | print 'hello' | alias=hello | - -= Active process = - -The test library keeps record which of the started processes is currently -active. By default it is latest process started with `Start Process`, -but `Switch Process` can be used to select a different one. Using -`Run Process` does not affect the active process. - -The keywords that operate on started processes will use the active process -by default, but it is possible to explicitly select a different process -using the ``handle`` argument. The handle can be the identifier returned by -`Start Process` or an ``alias`` explicitly given to `Start Process` or -`Run Process`. - -= Result object = - -`Run Process`, `Wait For Process` and `Terminate Process` keywords return a -result object that contains information about the process execution as its -attributes. The same result object, or some of its attributes, can also -be get using `Get Process Result` keyword. Attributes available in the -object are documented in the table below. - -| = Attribute = | = Explanation = | -| rc | Return code of the process as an integer. | -| stdout | Contents of the standard output stream. | -| stderr | Contents of the standard error stream. | -| stdout_path | Path where stdout was redirected or ``None`` if not redirected. | -| stderr_path | Path where stderr was redirected or ``None`` if not redirected. | - -Example: -| ${result} = | `Run Process` | program | -| `Should Be Equal As Integers` | ${result.rc} | 0 | -| `Should Match` | ${result.stdout} | Some t?xt* | -| `Should Be Empty` | ${result.stderr} | | -| ${stdout} = | `Get File` | ${result.stdout_path} | -| `Should Be Equal` | ${stdout} | ${result.stdout} | -| `File Should Be Empty` | ${result.stderr_path} | | - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Other strings are considered true regardless -their value, and other argument types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Terminate Process` | kill=True | # Strings are generally true. | -| `Terminate Process` | kill=yes | # Same as the above. | -| `Terminate Process` | kill=${TRUE} | # Python ``True`` is true. | -| `Terminate Process` | kill=${42} | # Numbers other than 0 are true. | - -False examples: -| `Terminate Process` | kill=False | # String ``false`` is false. | -| `Terminate Process` | kill=no | # Also string ``no`` is false. | -| `Terminate Process` | kill=${EMPTY} | # Empty string is false. | -| `Terminate Process` | kill=${FALSE} | # Python ``False`` is false. | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - -= Example = - -| ***** Settings ***** -| Library Process -| Suite Teardown `Terminate All Processes` kill=True -| -| ***** Test Cases ***** -| Example -| `Start Process` program arg1 arg2 alias=First -| ${handle} = `Start Process` command.sh arg | command2.sh shell=True cwd=/path -| ${result} = `Run Process` ${CURDIR}/script.py -| `Should Not Contain` ${result.stdout} FAIL -| `Terminate Process` ${handle} -| ${result} = `Wait For Process` First -| `Should Be Equal As Integers` ${result.rc} 0 - - -handle=None - -Returns the process ID (pid) of the process as an integer. - -If ``handle`` is not given, uses the current `active process`. - -Notice that the pid is not the same as the handle returned by -`Start Process` that is used internally by this library. - - - - - -handle=None - -Return the underlying ``subprocess.Popen`` object. - -If ``handle`` is not given, uses the current `active process`. - - - - - -handle=None -rc=False -stdout=False -stderr=False -stdout_path=False -stderr_path=False - -Returns the specified `result object` or some of its attributes. - -The given ``handle`` specifies the process whose results should be -returned. If no ``handle`` is given, results of the current `active -process` are returned. In either case, the process must have been -finishes before this keyword can be used. In practice this means -that processes started with `Start Process` must be finished either -with `Wait For Process` or `Terminate Process` before using this -keyword. - -If no other arguments than the optional ``handle`` are given, a whole -`result object` is returned. If one or more of the other arguments -are given any true value, only the specified attributes of the -`result object` are returned. These attributes are always returned -in the same order as arguments are specified in the keyword signature. -See `Boolean arguments` section for more details about true and false -values. - -Examples: -| Run Process | python | -c | print 'Hello, world!' | alias=myproc | -| # Get result object | | | -| ${result} = | Get Process Result | myproc | -| Should Be Equal | ${result.rc} | ${0} | -| Should Be Equal | ${result.stdout} | Hello, world! | -| Should Be Empty | ${result.stderr} | | -| # Get one attribute | | | -| ${stdout} = | Get Process Result | myproc | stdout=true | -| Should Be Equal | ${stdout} | Hello, world! | -| # Multiple attributes | | | -| ${stdout} | ${stderr} = | Get Process Result | myproc | stdout=yes | stderr=yes | -| Should Be Equal | ${stdout} | Hello, world! | -| Should Be Empty | ${stderr} | | - -Although getting results of a previously executed process can be handy -in general, the main use case for this keyword is returning results -over the remote library interface. The remote interface does not -support returning the whole result object, but individual attributes -can be returned without problems. - - - - - -handle=None - -Checks is the process running or not. - -If ``handle`` is not given, uses the current `active process`. - -Returns ``True`` if the process is still running and ``False`` otherwise. - - - - - -*args - -Joins arguments into one command line string. - -In resulting command line string arguments are delimited with a space, -arguments containing spaces are surrounded with quotes, and possible -quotes are escaped with a backslash. - -If this keyword is given only one argument and that is a list like -object, then the values of that list are joined instead. - -Example: -| ${cmd} = | Join Command Line | --option | value with spaces | -| Should Be Equal | ${cmd} | --option "value with spaces" | - -New in Robot Framework 2.9.2. - - - - - -handle=None -error_message=Process is not running. - -Verifies that the process is running. - -If ``handle`` is not given, uses the current `active process`. - -Fails if the process has stopped. - - - - - -handle=None -error_message=Process is running. - -Verifies that the process is not running. - -If ``handle`` is not given, uses the current `active process`. - -Fails if the process is still running. - - - - - -command -*arguments -**configuration - -Runs a process and waits for it to complete. - -``command`` and ``*arguments`` specify the command to execute and -arguments passed to it. See `Specifying command and arguments` for -more details. - -``**configuration`` contains additional configuration related to -starting processes and waiting for them to finish. See `Process -configuration` for more details about configuration related to starting -processes. Configuration related to waiting for processes consists of -``timeout`` and ``on_timeout`` arguments that have same semantics as -with `Wait For Process` keyword. By default there is no timeout, and -if timeout is defined the default action on timeout is ``terminate``. - -Returns a `result object` containing information about the execution. - -Note that possible equal signs in ``*arguments`` must be escaped -with a backslash (e.g. ``name\=value``) to avoid them to be passed in -as ``**configuration``. - -Examples: -| ${result} = | Run Process | python | -c | print 'Hello, world!' | -| Should Be Equal | ${result.stdout} | Hello, world! | -| ${result} = | Run Process | ${command} | stderr=STDOUT | timeout=10s | -| ${result} = | Run Process | ${command} | timeout=1min | on_timeout=continue | -| ${result} = | Run Process | java -Dname\=value Example | shell=True | cwd=${EXAMPLE} | - -This keyword does not change the `active process`. - - - - - -signal -handle=None -group=False - -Sends the given ``signal`` to the specified process. - -If ``handle`` is not given, uses the current `active process`. - -Signal can be specified either as an integer as a signal name. In the -latter case it is possible to give the name both with or without ``SIG`` -prefix, but names are case-sensitive. For example, all the examples -below send signal ``INT (2)``: - -| Send Signal To Process | 2 | | # Send to active process | -| Send Signal To Process | INT | | | -| Send Signal To Process | SIGINT | myproc | # Send to named process | - -This keyword is only supported on Unix-like machines, not on Windows. -What signals are supported depends on the system. For a list of -existing signals on your system, see the Unix man pages related to -signal handling (typically ``man signal`` or ``man 7 signal``). - -By default sends the signal only to the parent process, not to possible -child processes started by it. Notice that when `running processes in -shell`, the shell is the parent process and it depends on the system -does the shell propagate the signal to the actual started process. - -To send the signal to the whole process group, ``group`` argument can -be set to any true value (see `Boolean arguments`). This is not -supported by Jython, however. - - - - - -args -escaping=False - -Splits command line string into a list of arguments. - -String is split from spaces, but argument surrounded in quotes may -contain spaces in them. If ``escaping`` is given a true value, then -backslash is treated as an escape character. It can escape unquoted -spaces, quotes inside quotes, and so on, but it also requires using -double backslashes when using Windows paths. - -Examples: -| @{cmd} = | Split Command Line | --option "value with spaces" | -| Should Be True | $cmd == ['--option', 'value with spaces'] | - -New in Robot Framework 2.9.2. - - - - - -command -*arguments -**configuration - -Starts a new process on background. - -See `Specifying command and arguments` and `Process configuration` -for more information about the arguments, and `Run Process` keyword -for related examples. - -Makes the started process new `active process`. Returns an identifier -that can be used as a handle to activate the started process if needed. - -Processes are started so that they create a new process group. This -allows sending signals to and terminating also possible child -processes. This is not supported on Jython. - - - - - -handle - -Makes the specified process the current `active process`. - -The handle can be an identifier returned by `Start Process` or -the ``alias`` given to it explicitly. - -Example: -| Start Process | prog1 | alias=process1 | -| Start Process | prog2 | alias=process2 | -| # currently active process is process2 | -| Switch Process | process1 | -| # now active process is process1 | - - - - - -kill=False - -Terminates all still running processes started by this library. - -This keyword can be used in suite teardown or elsewhere to make -sure that all processes are stopped, - -By default tries to terminate processes gracefully, but can be -configured to forcefully kill them immediately. See `Terminate Process` -that this keyword uses internally for more details. - - - - - -handle=None -kill=False - -Stops the process gracefully or forcefully. - -If ``handle`` is not given, uses the current `active process`. - -By default first tries to stop the process gracefully. If the process -does not stop in 30 seconds, or ``kill`` argument is given a true value, -(see `Boolean arguments`) kills the process forcefully. Stops also all -the child processes of the originally started process. - -Waits for the process to stop after terminating it. Returns a `result -object` containing information about the execution similarly as `Wait -For Process`. - -On Unix-like machines graceful termination is done using ``TERM (15)`` -signal and killing using ``KILL (9)``. Use `Send Signal To Process` -instead if you just want to send either of these signals without -waiting for the process to stop. - -On Windows graceful termination is done using ``CTRL_BREAK_EVENT`` -event and killing using Win32 API function ``TerminateProcess()``. - -Examples: -| ${result} = | Terminate Process | | -| Should Be Equal As Integers | ${result.rc} | -15 | # On Unixes | -| Terminate Process | myproc | kill=true | - -Limitations: -- Graceful termination is not supported on Windows when using Jython. - Process is killed instead. -- Stopping the whole process group is not supported when using Jython. -- On Windows forceful kill only stops the main process, not possible - child processes. - - - - - -handle=None -timeout=None -on_timeout=continue - -Waits for the process to complete or to reach the given timeout. - -The process to wait for must have been started earlier with -`Start Process`. If ``handle`` is not given, uses the current -`active process`. - -``timeout`` defines the maximum time to wait for the process. It can be -given in -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format| -various time formats] supported by Robot Framework, for example, ``42``, -``42 s``, or ``1 minute 30 seconds``. - -``on_timeout`` defines what to do if the timeout occurs. Possible values -and corresponding actions are explained in the table below. Notice -that reaching the timeout never fails the test. - -| = Value = | = Action = | -| continue | The process is left running (default). | -| terminate | The process is gracefully terminated. | -| kill | The process is forcefully stopped. | - -See `Terminate Process` keyword for more details how processes are -terminated and killed. - -If the process ends before the timeout or it is terminated or killed, -this keyword returns a `result object` containing information about -the execution. If the process is left running, Python ``None`` is -returned instead. - -Examples: -| # Process ends cleanly | | | -| ${result} = | Wait For Process | example | -| Process Should Be Stopped | example | | -| Should Be Equal As Integers | ${result.rc} | 0 | -| # Process does not end | | | -| ${result} = | Wait For Process | timeout=42 secs | -| Process Should Be Running | | | -| Should Be Equal | ${result} | ${NONE} | -| # Kill non-ending process | | | -| ${result} = | Wait For Process | timeout=1min 30s | on_timeout=kill | -| Process Should Be Stopped | | | -| Should Be Equal As Integers | ${result.rc} | -9 | - - - - diff --git a/libspecs/Reserved.libspec b/libspecs/Reserved.libspec deleted file mode 100644 index 30d889d..0000000 --- a/libspecs/Reserved.libspec +++ /dev/null @@ -1,87 +0,0 @@ - - - -global -yes -Documentation for library ``Reserved``. - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - - -*varargs - - - - - - diff --git a/libspecs/Screenshot.libspec b/libspecs/Screenshot.libspec deleted file mode 100644 index 09033ae..0000000 --- a/libspecs/Screenshot.libspec +++ /dev/null @@ -1,132 +0,0 @@ - - -3.1.2 -test suite -yes -Test library for taking screenshots on the machine where tests are run. - -Notice that successfully taking screenshots requires tests to be run with -a physical or virtual display. - -= Using with Python = - -How screenshots are taken when using Python depends on the operating -system. On OSX screenshots are taken using the built-in ``screencapture`` -utility. On other operating systems you need to have one of the following -tools or Python modules installed. You can specify the tool/module to use -when `importing` the library. If no tool or module is specified, the first -one found will be used. - -- wxPython :: http://wxpython.org :: Required also by RIDE so many Robot - Framework users already have this module installed. -- PyGTK :: http://pygtk.org :: This module is available by default on most - Linux distributions. -- Pillow :: http://python-pillow.github.io :: - Only works on Windows. Also the original PIL package is supported. -- Scrot :: http://en.wikipedia.org/wiki/Scrot :: Not used on Windows. - Install with ``apt-get install scrot`` or similar. - -Using ``screencapture`` on OSX and specifying explicit screenshot module -are new in Robot Framework 2.9.2. The support for using ``scrot`` is new -in Robot Framework 3.0. - -= Using with Jython and IronPython = - -With Jython and IronPython this library uses APIs provided by JVM and .NET -platforms, respectively. These APIs are always available and thus no -external modules are needed. - -= Where screenshots are saved = - -By default screenshots are saved into the same directory where the Robot -Framework log file is written. If no log is created, screenshots are saved -into the directory where the XML output file is written. - -It is possible to specify a custom location for screenshots using -``screenshot_directory`` argument when `importing` the library and -using `Set Screenshot Directory` keyword during execution. It is also -possible to save screenshots using an absolute path. - - -screenshot_directory=None -screenshot_module=None - -Configure where screenshots are saved. - -If ``screenshot_directory`` is not given, screenshots are saved into -same directory as the log file. The directory can also be set using -`Set Screenshot Directory` keyword. - -``screenshot_module`` specifies the module or tool to use when using -this library on Python outside OSX. Possible values are ``wxPython``, -``PyGTK``, ``PIL`` and ``scrot``, case-insensitively. If no value is -given, the first module/tool found is used in that order. See `Using -with Python` for more information. - -Examples (use only one of these): -| =Setting= | =Value= | =Value= | -| Library | Screenshot | | -| Library | Screenshot | ${TEMPDIR} | -| Library | Screenshot | screenshot_module=PyGTK | - -Specifying explicit screenshot module is new in Robot Framework 2.9.2. - - - - - -path - -Sets the directory where screenshots are saved. - -It is possible to use ``/`` as a path separator in all operating -systems. Path to the old directory is returned. - -The directory can also be set in `importing`. - - - - - -name=screenshot -width=800px - -Takes a screenshot in JPEG format and embeds it into the log file. - -Name of the file where the screenshot is stored is derived from the -given ``name``. If the ``name`` ends with extension ``.jpg`` or -``.jpeg``, the screenshot will be stored with that exact name. -Otherwise a unique name is created by adding an underscore, a running -index and an extension to the ``name``. - -The name will be interpreted to be relative to the directory where -the log file is written. It is also possible to use absolute paths. -Using ``/`` as a path separator works in all operating systems. - -``width`` specifies the size of the screenshot in the log file. - -Examples: (LOGDIR is determined automatically by the library) -| Take Screenshot | | | # LOGDIR/screenshot_1.jpg (index automatically incremented) | -| Take Screenshot | mypic | | # LOGDIR/mypic_1.jpg (index automatically incremented) | -| Take Screenshot | ${TEMPDIR}/mypic | | # /tmp/mypic_1.jpg (index automatically incremented) | -| Take Screenshot | pic.jpg | | # LOGDIR/pic.jpg (always uses this file) | -| Take Screenshot | images/login.jpg | 80% | # Specify both name and width. | -| Take Screenshot | width=550px | | # Specify only width. | - -The path where the screenshot is saved is returned. - - - - - -name=screenshot - -Takes a screenshot and links it from the log file. - -This keyword is otherwise identical to `Take Screenshot` but the saved -screenshot is not embedded into the log file. The screenshot is linked -so it is nevertheless easily available. - - - - diff --git a/libspecs/SeleniumLibrary_104a884.libspec b/libspecs/SeleniumLibrary_104a884.libspec deleted file mode 100644 index 7e33dc1..0000000 --- a/libspecs/SeleniumLibrary_104a884.libspec +++ /dev/null @@ -1,3676 +0,0 @@ - - -4.3.0 -global -yes -SeleniumLibrary is a web testing library for Robot Framework. - -This document explains how to use keywords provided by SeleniumLibrary. -For information about installation, support, and more, please visit the -[https://github.com/robotframework/SeleniumLibrary|project pages]. -For more information about Robot Framework, see http://robotframework.org. - -SeleniumLibrary uses the Selenium WebDriver modules internally to -control a web browser. See http://seleniumhq.org for more information -about Selenium in general and SeleniumLibrary README.rst -[https://github.com/robotframework/SeleniumLibrary#browser-drivers|Browser drivers chapter] -for more details about WebDriver binary installation. - -== Table of contents == - -- `Locating elements` -- `Browser and Window` -- `Timeouts, waits, and delays` -- `Run-on-failure functionality` -- `Boolean arguments` -- `EventFiringWebDriver` -- `Thread support` -- `Plugins` -- `Importing` -- `Shortcuts` -- `Keywords` - -= Locating elements = - -All keywords in SeleniumLibrary that need to interact with an element -on a web page take an argument typically named ``locator`` that specifies -how to find the element. Most often the locator is given as a string -using the locator syntax described below, but `using WebElements` is -possible too. - -== Locator syntax == - -SeleniumLibrary supports finding elements based on different strategies -such as the element id, XPath expressions, or CSS selectors. The strategy -can either be explicitly specified with a prefix or the strategy can be -implicit. - -=== Default locator strategy === - -By default, locators are considered to use the keyword specific default -locator strategy. All keywords support finding elements based on ``id`` -and ``name`` attributes, but some keywords support additional attributes -or other values that make sense in their context. For example, `Click -Link` supports the ``href`` attribute and the link text and addition -to the normal ``id`` and ``name``. - -Examples: - -| `Click Element` | example | # Match based on ``id`` or ``name``. | -| `Click Link` | example | # Match also based on link text and ``href``. | -| `Click Button` | example | # Match based on ``id``, ``name`` or ``value``. | - -If a locator accidentally starts with a prefix recognized as `explicit -locator strategy` or `implicit XPath strategy`, it is possible to use -the explicit ``default`` prefix to enable the default strategy. - -Examples: - -| `Click Element` | name:foo | # Find element with name ``foo``. | -| `Click Element` | default:name:foo | # Use default strategy with value ``name:foo``. | -| `Click Element` | //foo | # Find element using XPath ``//foo``. | -| `Click Element` | default: //foo | # Use default strategy with value ``//foo``. | - -=== Explicit locator strategy === - -The explicit locator strategy is specified with a prefix using either -syntax ``strategy:value`` or ``strategy=value``. The former syntax -is preferred because the latter is identical to Robot Framework's -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#named-argument-syntax| -named argument syntax] and that can cause problems. Spaces around -the separator are ignored, so ``id:foo``, ``id: foo`` and ``id : foo`` -are all equivalent. - -Locator strategies that are supported by default are listed in the table -below. In addition to them, it is possible to register `custom locators`. - -| = Strategy = | = Match based on = | = Example = | -| id | Element ``id``. | ``id:example`` | -| name | ``name`` attribute. | ``name:example`` | -| identifier | Either ``id`` or ``name``. | ``identifier:example`` | -| class | Element ``class``. | ``class:example`` | -| tag | Tag name. | ``tag:div`` | -| xpath | XPath expression. | ``xpath://div[@id="example"]`` | -| css | CSS selector. | ``css:div#example`` | -| dom | DOM expression. | ``dom:document.images[5]`` | -| link | Exact text a link has. | ``link:The example`` | -| partial link | Partial link text. | ``partial link:he ex`` | -| sizzle | Sizzle selector deprecated. | ``sizzle:div.example`` | -| jquery | jQuery expression. | ``jquery:div.example`` | -| default | Keyword specific default behavior. | ``default:example`` | - -See the `Default locator strategy` section below for more information -about how the default strategy works. Using the explicit ``default`` -prefix is only necessary if the locator value itself accidentally -matches some of the explicit strategies. - -Different locator strategies have different pros and cons. Using ids, -either explicitly like ``id:foo`` or by using the `default locator -strategy` simply like ``foo``, is recommended when possible, because -the syntax is simple and locating elements by id is fast for browsers. -If an element does not have an id or the id is not stable, other -solutions need to be used. If an element has a unique tag name or class, -using ``tag``, ``class`` or ``css`` strategy like ``tag:h1``, -``class:example`` or ``css:h1.example`` is often an easy solution. In -more complex cases using XPath expressions is typically the best -approach. They are very powerful but a downside is that they can also -get complex. - -Examples: - -| `Click Element` | id:foo | # Element with id 'foo'. | -| `Click Element` | css:div#foo h1 | # h1 element under div with id 'foo'. | -| `Click Element` | xpath: //div[@id="foo"]//h1 | # Same as the above using XPath, not CSS. | -| `Click Element` | xpath: //*[contains(text(), "example")] | # Element containing text 'example'. | - -*NOTE:* - -- The ``strategy:value`` syntax is only supported by SeleniumLibrary 3.0 - and newer. -- Using the ``sizzle`` strategy or its alias ``jquery`` requires that - the system under test contains the jQuery library. -- Prior to SeleniumLibrary 3.0, table related keywords only supported - ``xpath``, ``css`` and ``sizzle/jquery`` strategies. - -=== Implicit XPath strategy === - -If the locator starts with ``//`` or ``(//``, the locator is considered -to be an XPath expression. In other words, using ``//div`` is equivalent -to using explicit ``xpath://div``. - -Examples: - -| `Click Element` | //div[@id="foo"]//h1 | -| `Click Element` | (//div)[2] | - -The support for the ``(//`` prefix is new in SeleniumLibrary 3.0. - -== Using WebElements == - -In addition to specifying a locator as a string, it is possible to use -Selenium's WebElement objects. This requires first getting a WebElement, -for example, by using the `Get WebElement` keyword. - -| ${elem} = | `Get WebElement` | id:example | -| `Click Element` | ${elem} | | - -== Custom locators == - -If more complex lookups are required than what is provided through the -default locators, custom lookup strategies can be created. Using custom -locators is a two part process. First, create a keyword that returns -a WebElement that should be acted on: - -| Custom Locator Strategy | [Arguments] | ${browser} | ${locator} | ${tag} | ${constraints} | -| | ${element}= | Execute Javascript | return window.document.getElementById('${locator}'); | -| | [Return] | ${element} | - -This keyword is a reimplementation of the basic functionality of the -``id`` locator where ``${browser}`` is a reference to a WebDriver -instance and ``${locator}`` is the name of the locator strategy. To use -this locator, it must first be registered by using the -`Add Location Strategy` keyword: - -| `Add Location Strategy` | custom | Custom Locator Strategy | - -The first argument of `Add Location Strategy` specifies the name of -the strategy and it must be unique. After registering the strategy, -the usage is the same as with other locators: - -| `Click Element` | custom:example | - -See the `Add Location Strategy` keyword for more details. - -= Browser and Window = - -There is different conceptual meaning when SeleniumLibrary talks -about windows or browsers. This chapter explains those differences. - -== Browser == - -When `Open Browser` or `Create WebDriver` keyword is called, it -will create a new Selenium WebDriver instance by using the -[https://www.seleniumhq.org/docs/03_webdriver.jsp|Selenium WebDriver] -API. In SeleniumLibrary terms, a new browser is created. It is -possible to start multiple independent browsers (Selenium Webdriver -instances) at the same time, by calling `Open Browser` or -`Create WebDriver` multiple times. These browsers are usually -independent of each other and do not share data like cookies, -sessions or profiles. Typically when the browser starts, it -creates a single window which is shown to the user. - -== Window == - -Windows are the part of a browser that loads the web site and presents -it to the user. All content of the site is the content of the window. -Windows are children of a browser. In SeleniumLibrary browser is a -synonym for WebDriver instance. One browser may have multiple -windows. Windows can appear as tabs, as separate windows or pop-ups with -different position and size. Windows belonging to the same browser -typically share the sessions detail, like cookies. If there is a -need to separate sessions detail, example login with two different -users, two browsers (Selenium WebDriver instances) must be created. -New windows can be opened example by the application under test or -by example `Execute Javascript` keyword: - -| `Execute Javascript` window.open() # Opens a new window with location about:blank - -The example below opens multiple browsers and windows, -to demonstrate how the different keywords can be used to interact -with browsers, and windows attached to these browsers. - -Structure: -| BrowserA -| Window 1 (location=https://robotframework.org/) -| Window 2 (location=https://robocon.io/) -| Window 3 (location=https://github.com/robotframework/) -| -| BrowserB -| Window 1 (location=https://github.com/) - -Example: -| `Open Browser` | https://robotframework.org | ${BROWSER} | alias=BrowserA | # BrowserA with first window is opened. | -| `Execute Javascript` | window.open() | | | # In BrowserA second window is opened. | -| `Switch Window` | locator=NEW | | | # Switched to second window in BrowserA | -| `Go To` | https://robocon.io | | | # Second window navigates to robocon site. | -| `Execute Javascript` | window.open() | | | # In BrowserA third window is opened. | -| ${handle} | `Switch Window` | locator=NEW | | # Switched to third window in BrowserA | -| `Go To` | https://github.com/robotframework/ | | | # Third windows goes to robot framework github site. | -| `Open Browser` | https://github.com | ${BROWSER} | alias=BrowserB | # BrowserB with first windows is opened. | -| ${location} | `Get Location` | | | # ${location} is: https://www.github.com | -| `Switch Window` | ${handle} | browser=BrowserA | | # BrowserA second windows is selected. | -| ${location} | `Get Location` | | | # ${location} = https://robocon.io/ | -| @{locations 1} | `Get Locations` | | | # By default, lists locations under the currectly active browser (BrowserA). | -| @{locations 2} | `Get Locations` | browser=ALL | | # By using browser=ALL argument keyword list all locations from all browsers. | - -The above example, @{locations 1} contains the following items: -https://robotframework.org/, https://robocon.io/ and -https://github.com/robotframework/'. The @{locations 2} -contains the following items: https://robotframework.org/, -https://robocon.io/, https://github.com/robotframework/' -and 'https://github.com/. - -= Timeouts, waits, and delays = - -This section discusses different ways how to wait for elements to -appear on web pages and to slow down execution speed otherwise. -It also explains the `time format` that can be used when setting various -timeouts, waits, and delays. - -== Timeout == - -SeleniumLibrary contains various keywords that have an optional -``timeout`` argument that specifies how long these keywords should -wait for certain events or actions. These keywords include, for example, -``Wait ...`` keywords and keywords related to alerts. Additionally -`Execute Async Javascript`. Although it does not have ``timeout``, -argument, uses a timeout to define how long asynchronous JavaScript -can run. - -The default timeout these keywords use can be set globally either by -using the `Set Selenium Timeout` keyword or with the ``timeout`` argument -when `importing` the library. See `time format` below for supported -timeout syntax. - -== Implicit wait == - -Implicit wait specifies the maximum time how long Selenium waits when -searching for elements. It can be set by using the `Set Selenium Implicit -Wait` keyword or with the ``implicit_wait`` argument when `importing` -the library. See [https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp| -Selenium documentation] for more information about this functionality. - -See `time format` below for supported syntax. - -== Selenium speed == - -Selenium execution speed can be slowed down globally by using `Set -Selenium speed` keyword. This functionality is designed to be used for -demonstrating or debugging purposes. Using it to make sure that elements -appear on a page is not a good idea. The above-explained timeouts -and waits should be used instead. - -See `time format` below for supported syntax. - -== Time format == - -All timeouts and waits 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``). For more information about -the time syntax see the -[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|Robot Framework User Guide]. - -= Run-on-failure functionality = - -SeleniumLibrary has a handy feature that it can automatically execute -a keyword if any of its own keywords fails. By default, it uses the -`Capture Page Screenshot` keyword, but this can be changed either by -using the `Register Keyword To Run On Failure` keyword or with the -``run_on_failure`` argument when `importing` the library. It is -possible to use any keyword from any imported library or resource file. - -The run-on-failure functionality can be disabled by using a special value -``NOTHING`` or anything considered false (see `Boolean arguments`) -such as ``NONE``. - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is either empty or case-insensitively equal to ``false``, ``no``, ``off``, - ``0`` or ``none``. Other strings are considered true regardless of their value and -other argument types are tested using the same -[https://docs.python.org/3/library/stdtypes.html#truth-value-testing|rules as in Python]. - -True examples: - -| `Set Screenshot Directory` | ${RESULTS} | persist=True | # Strings are generally true. | -| `Set Screenshot Directory` | ${RESULTS} | persist=yes | # Same as the above. | -| `Set Screenshot Directory` | ${RESULTS} | persist=${TRUE} | # Python True is true. | -| `Set Screenshot Directory` | ${RESULTS} | persist=${42} | # Numbers other than 0 are true. | - -False examples: - -| `Set Screenshot Directory` | ${RESULTS} | persist=False | # String false is false. | -| `Set Screenshot Directory` | ${RESULTS} | persist=no | # Also string no is false. | -| `Set Screenshot Directory` | ${RESULTS} | persist=NONE | # String NONE is false. | -| `Set Screenshot Directory` | ${RESULTS} | persist=${EMPTY} | # Empty string is false. | -| `Set Screenshot Directory` | ${RESULTS} | persist=${FALSE} | # Python False is false. | -| `Set Screenshot Directory` | ${RESULTS} | persist=${NONE} | # Python None is false. | - -Note that prior to SeleniumLibrary 3.0, all non-empty strings, including -``false``, ``no`` and ``none``, were considered true. Starting from -SeleniumLibrary 4.0, strings ``0`` and ``off`` are considered as false. - -= EventFiringWebDriver = - -The SeleniumLibrary offers support for -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver]. -See the Selenium and SeleniumLibrary -[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#EventFiringWebDriver|EventFiringWebDriver support] -documentation for further details. - -EventFiringWebDriver is new in SeleniumLibrary 4.0 - -= Thread support = - -SeleniumLibrary is not thread-safe. This is mainly due because the underlying -[https://github.com/SeleniumHQ/selenium/wiki/Frequently-Asked-Questions#q-is-webdriver-thread-safe| -Selenium tool is not thread-safe] within one browser/driver instance. -Because of the limitation in the Selenium side, the keywords or the -API provided by the SeleniumLibrary is not thread-safe. - -= Plugins = - -SeleniumLibrary offers plugins as a way to modify and add library keywords and modify some of the internal -functionality without creating a new library or hacking the source code. See -[https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst#Plugins|plugin API] -documentation for further details. - -Plugin API is new SeleniumLibrary 4.0 - - -timeout=5.0 -implicit_wait=0.0 -run_on_failure=Capture Page Screenshot -screenshot_root_directory=None -plugins=None -event_firing_webdriver=None - -SeleniumLibrary can be imported with several optional arguments. - -- ``timeout``: - Default value for `timeouts` used with ``Wait ...`` keywords. -- ``implicit_wait``: - Default value for `implicit wait` used when locating elements. -- ``run_on_failure``: - Default action for the `run-on-failure functionality`. -- ``screenshot_root_directory``: - Path to folder where possible screenshots are created or EMBED. - See `Set Screenshot Directory` keyword for further details about EMBED. - If not given, the directory where the log file is written is used. -- ``plugins``: - Allows extending the SeleniumLibrary with external Python classes. -- ``event_firing_webdriver``: - Class for wrapping Selenium with - [https://seleniumhq.github.io/selenium/docs/api/py/webdriver_support/selenium.webdriver.support.event_firing_webdriver.html#module-selenium.webdriver.support.event_firing_webdriver|EventFiringWebDriver] - - - - - -name -value -path=None -domain=None -secure=None -expiry=None - -Adds a cookie to your current session. - -``name`` and ``value`` are required, ``path``, ``domain``, ``secure`` -and ``expiry`` are optional. Expiry supports the same formats as -the [http://robotframework.org/robotframework/latest/libraries/DateTime.html|DateTime] -library or an epoch timestamp. - -Example: -| `Add Cookie` | foo | bar | | -| `Add Cookie` | foo | bar | domain=example.com | -| `Add Cookie` | foo | bar | expiry=2027-09-28 16:21:35 | # Expiry as timestamp. | -| `Add Cookie` | foo | bar | expiry=1822137695 | # Expiry as epoch seconds. | - -Prior to SeleniumLibrary 3.0 setting expiry did not work. - - - - - -strategy_name -strategy_keyword -persist=False - -Adds a custom location strategy. - -See `Custom locators` for information on how to create and use -custom strategies. `Remove Location Strategy` can be used to -remove a registered strategy. - -Location strategies are automatically removed after leaving the -current scope by default. Setting ``persist`` to a true value (see -`Boolean arguments`) will cause the location strategy to stay -registered throughout the life of the test. - - - - - -text= -action=ACCEPT -timeout=None - -Verifies that an alert is present and by default, accepts it. - -Fails if no alert is present. If ``text`` is a non-empty string, -then it is used to verify alert's message. The alert is accepted -by default, but that behavior can be controlled by using the -``action`` argument same way as with `Handle Alert`. - -``timeout`` specifies how long to wait for the alert to appear. -If it is not given, the global default `timeout` is used instead. - -``action`` and ``timeout`` arguments are new in SeleniumLibrary 3.0. -In earlier versions, the alert was always accepted and a timeout was -hardcoded to one second. - - - - - -action=ACCEPT -timeout=0 - -Verifies that no alert is present. - -If the alert actually exists, the ``action`` argument determines -how it should be handled. By default, the alert is accepted, but -it can be also dismissed or left open the same way as with the -`Handle Alert` keyword. - -``timeout`` specifies how long to wait for the alert to appear. -By default, is not waited for the alert at all, but a custom time can -be given if alert may be delayed. See the `time format` section -for information about the syntax. - -New in SeleniumLibrary 3.0. - - - - - -locator -id - -Assigns a temporary ``id`` to the element specified by ``locator``. - -This is mainly useful if the locator is complicated and/or slow XPath -expression and it is needed multiple times. Identifier expires when -the page is reloaded. - -See the `Locating elements` section for details about the locator -syntax. - -Example: -| `Assign ID to Element` | //ul[@class='example' and ./li[contains(., 'Stuff')]] | my id | -| `Page Should Contain Element` | my id | - - - - - -locator -filename=selenium-element-screenshot-{index}.png - -Captures a screenshot from the element identified by ``locator`` and embeds it into log file. - -See `Capture Page Screenshot` for details about ``filename`` argument. -See the `Locating elements` section for details about the locator -syntax. - -An absolute path to the created element screenshot is returned. - -Support for capturing the screenshot from an element has limited support -among browser vendors. Please check the browser vendor driver documentation -does the browser support capturing a screenshot from an element. - -New in SeleniumLibrary 3.3. Support for EMBED is new in SeleniumLibrary 4.2. - -Examples: -| `Capture Element Screenshot` | id:image_id | | -| `Capture Element Screenshot` | id:image_id | ${OUTPUTDIR}/id_image_id-1.png | -| `Capture Element Screenshot` | id:image_id | EMBED | - - - - - -filename=selenium-screenshot-{index}.png - -Takes a screenshot of the current page and embeds it into a log file. - -``filename`` argument specifies the name of the file to write the -screenshot into. The directory where screenshots are saved can be -set when `importing` the library or by using the `Set Screenshot -Directory` keyword. If the directory is not configured, screenshots -are saved to the same directory where Robot Framework's log file is -written. - -If ``filename`` equals to EMBED (case insensitive), then screenshot -is embedded as Base64 image to the log.html. In this case file is not -created in the filesystem. - -Starting from SeleniumLibrary 1.8, if ``filename`` contains marker -``{index}``, it will be automatically replaced with an unique running -index, preventing files to be overwritten. Indices start from 1, -and how they are represented can be customized using Python's -[https://docs.python.org/3/library/string.html#format-string-syntax| -format string syntax]. - -An absolute path to the created screenshot file is returned or if -``filename`` equals to EMBED, word `EMBED` is returned. - -Support for EMBED is new in SeleniumLibrary 4.2 - -Examples: -| `Capture Page Screenshot` | | -| `File Should Exist` | ${OUTPUTDIR}/selenium-screenshot-1.png | -| ${path} = | `Capture Page Screenshot` | -| `File Should Exist` | ${OUTPUTDIR}/selenium-screenshot-2.png | -| `File Should Exist` | ${path} | -| `Capture Page Screenshot` | custom_name.png | -| `File Should Exist` | ${OUTPUTDIR}/custom_name.png | -| `Capture Page Screenshot` | custom_with_index_{index}.png | -| `File Should Exist` | ${OUTPUTDIR}/custom_with_index_1.png | -| `Capture Page Screenshot` | formatted_index_{index:03}.png | -| `File Should Exist` | ${OUTPUTDIR}/formatted_index_001.png | -| `Capture Page Screenshot` | EMBED | -| `File Should Not Exist` | EMBED | - - - - - -locator - -Verifies checkbox ``locator`` is selected/checked. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Verifies checkbox ``locator`` is not selected/checked. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -file_path - -Inputs the ``file_path`` into the file input field ``locator``. - -This keyword is most often used to input files into upload forms. -The keyword does not check ``file_path`` is the file or folder -available on the machine where tests are executed. If the ``file_path`` -points at a file and when using Selenium Grid, Selenium will -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_remote/selenium.webdriver.remote.command.html?highlight=upload#selenium.webdriver.remote.command.Command.UPLOAD_FILE|magically], -transfer the file from the machine where the tests are executed -to the Selenium Grid node where the browser is running. -Then Selenium will send the file path, from the nodes file -system, to the browser. - -That ``file_path`` is not checked, is new in SeleniumLibrary 4.0. - -Example: -| `Choose File` | my_upload_field | ${CURDIR}/trades.csv | - - - - - -locator - -Clears the value of the text-input-element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -modifier=False - -Clicks the button identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, buttons are -searched using ``id``, ``name``, and ``value``. - -See the `Click Element` keyword for details about the -``modifier`` argument. - -The ``modifier`` argument is new in SeleniumLibrary 3.3 - - - - - -locator -modifier=False -action_chain=False - -Click the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -The ``modifier`` argument can be used to pass -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html#selenium.webdriver.common.keys.Keys|Selenium Keys] -when clicking the element. The `+` can be used as a separator -for different Selenium Keys. The `CTRL` is internally translated to -the `CONTROL` key. The ``modifier`` is space and case insensitive, example -"alt" and " aLt " are supported formats to -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html#selenium.webdriver.common.keys.Keys.ALT|ALT key] -. If ``modifier`` does not match to Selenium Keys, keyword fails. - -If ``action_chain`` argument is true, see `Boolean arguments` for more -details on how to set boolean argument, then keyword uses ActionChain -based click instead of the <web_element>.click() function. If both -``action_chain`` and ``modifier`` are defined, the click will be -performed using ``modifier`` and ``action_chain`` will be ignored. - -Example: -| Click Element | id:button | | # Would click element without any modifiers. | -| Click Element | id:button | CTRL | # Would click element with CTLR key pressed down. | -| Click Element | id:button | CTRL+ALT | # Would click element with CTLR and ALT keys pressed down. | -| Click Element | id:button | action_chain=True | # Clicks the button using an Selenium ActionChains | - -The ``modifier`` argument is new in SeleniumLibrary 3.2 -The ``action_chain`` argument is new in SeleniumLibrary 4.1 - - - - - -locator -xoffset -yoffset - -Click the element ``locator`` at ``xoffset/yoffset``. - -The Cursor is moved and the center of the element and x/y coordinates are -calculated from that point. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -modifier=False - -Clicks an image identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, images are searched -using ``id``, ``name``, ``src`` and ``alt``. - -See the `Click Element` keyword for details about the -``modifier`` argument. - -The ``modifier`` argument is new in SeleniumLibrary 3.3 - - - - - -locator -modifier=False - -Clicks a link identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, links are searched -using ``id``, ``name``, ``href`` and the link text. - -See the `Click Element` keyword for details about the -``modifier`` argument. - -The ``modifier`` argument is new in SeleniumLibrary 3.3 - - - - - - -Closes all open browsers and resets the browser cache. - -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. - - - - - - -Closes the current browser. - - - - - - -Closes currently opened and selected browser window/tab. - - - - - -locator - -Will cover elements identified by ``locator`` with a blue div without breaking page layout. - -See the `Locating elements` section for details about the locator -syntax. - -New in SeleniumLibrary 3.3.0 - -Example: -|`Cover Element` | css:div#container | - - - - - -driver_name -alias=None -kwargs={} -**init_kwargs - -Creates an instance of Selenium WebDriver. - -Like `Open Browser`, but allows passing arguments to the created -WebDriver instance directly. This keyword should only be used if -the functionality provided by `Open Browser` is not adequate. - -``driver_name`` must be a WebDriver implementation name like Firefox, -Chrome, Ie, Opera, Safari, PhantomJS, or Remote. - -The initialized WebDriver can be configured either with a Python -dictionary ``kwargs`` or by using keyword arguments ``**init_kwargs``. -These arguments are passed directly to WebDriver without any -processing. See [https://seleniumhq.github.io/selenium/docs/api/py/api.html| -Selenium API documentation] for details about the supported arguments. - -Examples: -| # Use proxy with Firefox | | | | -| ${proxy}= | `Evaluate` | selenium.webdriver.Proxy() | modules=selenium, selenium.webdriver | -| ${proxy.http_proxy}= | `Set Variable` | localhost:8888 | | -| `Create Webdriver` | Firefox | proxy=${proxy} | | -| # Use proxy with PhantomJS | | | | -| ${service args}= | `Create List` | --proxy=192.168.132.104:8888 | | -| `Create Webdriver` | PhantomJS | service_args=${service args} | | - -Returns the index of this browser instance which can be used later to -switch back to it. Index starts from 1 and is reset back to it when -`Close All Browsers` keyword is used. See `Switch Browser` for an -example. - - - - - -text -loglevel=TRACE - -Verifies that the current frame contains ``text``. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - -Prior to SeleniumLibrary 3.0 this keyword was named -`Current Frame Contains`. - - - - - -text -loglevel=TRACE - -Verifies that the current frame does not contain ``text``. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - - - - - - -Deletes all cookies. - - - - - -name - -Deletes the cookie matching ``name``. - -If the cookie is not found, nothing happens. - - - - - -locator - -Double clicks the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -target - -Drags the element identified by ``locator`` into the ``target`` element. - -The ``locator`` argument is the locator of the dragged element -and the ``target`` is the locator of the target. See the -`Locating elements` section for details about the locator syntax. - -Example: -| `Drag And Drop` | css:div#element | css:div.target | - - - - - -locator -xoffset -yoffset - -Drags the element identified with ``locator`` by ``xoffset/yoffset``. - -See the `Locating elements` section for details about the locator -syntax. - -The element will be moved by ``xoffset`` and ``yoffset``, each of which -is a negative or positive number specifying the offset. - -Example: -| `Drag And Drop By Offset` | myElem | 50 | -35 | # Move myElem 50px right and 35px down | - - - - - -locator -attribute -expected -message=None - -Verifies element identified by ``locator`` contains expected attribute value. - -See the `Locating elements` section for details about the locator -syntax. - -Example: -`Element Attribute Value Should Be` | css:img | href | value - -New in SeleniumLibrary 3.2. - - - - - -locator - -Verifies that element identified by ``locator`` is disabled. - -This keyword considers also elements that are read-only to be -disabled. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Verifies that element identified by ``locator`` is enabled. - -This keyword considers also elements that are read-only to be -disabled. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Verifies that element identified by ``locator`` is focused. - -See the `Locating elements` section for details about the locator -syntax. - -New in SeleniumLibrary 3.0. - - - - - -locator -message=None - -Verifies that 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. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - - - - - -locator -expected -message=None -ignore_case=False - -Verifies that element ``locator`` contains text ``expected``. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - -The ``ignore_case`` argument can be set to True to compare case -insensitive, default is False. New in SeleniumLibrary 3.1. - -``ignore_case`` argument is new in SeleniumLibrary 3.1. - -Use `Element Text Should Be` if you want to match the exact text, -not a substring. - - - - - -locator -message=None - -Verifies that the element identified by ``locator`` is NOT visible. - -Passes if the element does not exists. See `Element Should Be Visible` -for more information about visibility and supported arguments. - - - - - -locator -expected -message=None -ignore_case=False - -Verifies that element ``locator`` does not contain text ``expected``. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - -The ``ignore_case`` argument can be set to True to compare case -insensitive, default is False. - -``ignore_case`` argument new in SeleniumLibrary 3.1. - - - - - -locator -expected -message=None -ignore_case=False - -Verifies that element ``locator`` contains exact the text ``expected``. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - -The ``ignore_case`` argument can be set to True to compare case -insensitive, default is False. - -``ignore_case`` argument is new in SeleniumLibrary 3.1. - -Use `Element Should Contain` if a substring match is desired. - - - - - -locator -not_expected -message=None -ignore_case=False - -Verifies that element ``locator`` does not contain exact the text ``not_expected``. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - -The ``ignore_case`` argument can be set to True to compare case -insensitive, default is False. - -New in SeleniumLibrary 3.1.1 - - - - - -*code - -Executes asynchronous JavaScript code with possible arguments. - -Similar to `Execute Javascript` except that scripts executed with -this keyword must explicitly signal they are finished by invoking the -provided callback. This callback is always injected into the executed -function as the last argument. - -Scripts must complete within the script timeout or this keyword will -fail. See the `Timeout` section for more information. - -Starting from SeleniumLibrary 3.2 it is possible to provide JavaScript -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_remote/selenium.webdriver.remote.webdriver.html#selenium.webdriver.remote.webdriver.WebDriver.execute_async_script| -arguments] as part of ``code`` argument. See `Execute Javascript` for -more details. - -Examples: -| `Execute Async JavaScript` | var callback = arguments[arguments.length - 1]; window.setTimeout(callback, 2000); | -| `Execute Async JavaScript` | ${CURDIR}/async_js_to_execute.js | -| ${result} = | `Execute Async JavaScript` | -| ... | var callback = arguments[arguments.length - 1]; | -| ... | function answer(){callback("text");}; | -| ... | window.setTimeout(answer, 2000); | -| `Should Be Equal` | ${result} | text | - - - - - -*code - -Executes the given JavaScript code with possible arguments. - -``code`` may be divided into multiple cells in the test data and -``code`` may contain multiple lines of code and arguments. In that case, -the JavaScript code parts are concatenated together without adding -spaces and optional arguments are separated from ``code``. - -If ``code`` is a 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. - -The JavaScript executes in the context of the currently selected -frame or window as the body of an anonymous function. Use ``window`` -to refer to the window of your application and ``document`` to refer -to the document object of the current frame or window, e.g. -``document.getElementById('example')``. - -This keyword returns whatever the executed JavaScript code returns. -Return values are converted to the appropriate Python types. - -Starting from SeleniumLibrary 3.2 it is possible to provide JavaScript -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_remote/selenium.webdriver.remote.webdriver.html#selenium.webdriver.remote.webdriver.WebDriver.execute_script| -arguments] as part of ``code`` argument. The JavaScript code and -arguments must be separated with `JAVASCRIPT` and `ARGUMENTS` markers -and must be used exactly with this format. If the Javascript code is -first, then the `JAVASCRIPT` marker is optional. The order of -`JAVASCRIPT` and `ARGUMENTS` markers can be swapped, but if `ARGUMENTS` -is the first marker, then `JAVASCRIPT` marker is mandatory. It is only -allowed to use `JAVASCRIPT` and `ARGUMENTS` markers only one time in the -``code`` argument. - -Examples: -| `Execute JavaScript` | window.myFunc('arg1', 'arg2') | -| `Execute JavaScript` | ${CURDIR}/js_to_execute.js | -| `Execute JavaScript` | alert(arguments[0]); | ARGUMENTS | 123 | -| `Execute JavaScript` | ARGUMENTS | 123 | JAVASCRIPT | alert(arguments[0]); | - - - - - -locator -text -loglevel=TRACE - -Verifies that frame identified by ``locator`` contains ``text``. - -See the `Locating elements` section for details about the locator -syntax. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - - - - - - -Returns a list containing ids of all links found in current page. - -If a link has no id, an empty string will be in the list instead. - - - - - - -Returns aliases of all active browser that has an alias as NormalizedDict. -The dictionary contains the aliases as keys and the index as value. -This can be accessed as dictionary ``${aliases.key}`` or as list ``@{aliases}[0]``. - -Example: -| `Open Browser` | https://example.com | alias=BrowserA | | -| `Open Browser` | https://example.com | alias=BrowserB | | -| &{aliases} | `Get Browser Aliases` | | # &{aliases} = { BrowserA=1|BrowserB=2 } | -| `Log` | ${aliases.BrowserA} | | # logs ``1`` | -| FOR | ${alias} | IN | @{aliases} | -| | `Log` | ${alias} | # logs ``BrowserA`` and ``BrowserB`` | -| END | | | | - -See `Switch Browser` for more information and examples. - -New in SeleniumLibrary 4.0 - - - - - - -Returns index of all active browser as list. - -Example: -| @{browser_ids}= | Get Browser Ids | | | -| FOR | ${id} | IN | @{browser_ids} | -| | @{window_titles}= | Get Window Titles | browser=${id} | -| | Log | Browser ${id} has these windows: ${window_titles} | | -| END | | | | - -See `Switch Browser` for more information and examples. - -New in SeleniumLibrary 4.0 - - - - - -name - -Returns information of cookie with ``name`` as an object. - -If no cookie is found with ``name``, keyword fails. The cookie object -contains details about the cookie. Attributes available in the object -are documented in the table below. - -| = Attribute = | = Explanation = | -| name | The name of a cookie. | -| value | Value of the cookie. | -| path | Indicates a URL path, for example ``/``. | -| domain | The domain, the cookie is visible to. | -| secure | When true, the cookie is only used with HTTPS connections. | -| httpOnly | When true, the cookie is not accessible via JavaScript. | -| expiry | Python datetime object indicating when the cookie expires. | -| extra | Possible attributes outside of the WebDriver specification | - -See the -[https://w3c.github.io/webdriver/#cookies|WebDriver specification] -for details about the cookie information. -Notice that ``expiry`` is specified as a -[https://docs.python.org/3/library/datetime.html#datetime.datetime|datetime object], -not as seconds since Unix Epoch like WebDriver natively does. - -In some cases, example when running a browser in the cloud, it is possible that -the cookie contains other attributes than is defined in the -[https://w3c.github.io/webdriver/#cookies|WebDriver specification]. -These other attributes are available in an ``extra`` attribute in the cookie -object and it contains a dictionary of the other attributes. The ``extra`` -attribute is new in SeleniumLibrary 4.0. - -Example: -| `Add Cookie` | foo | bar | -| ${cookie} = | `Get Cookie` | foo | -| `Should Be Equal` | ${cookie.name} | bar | -| `Should Be Equal` | ${cookie.value} | foo | -| `Should Be True` | ${cookie.expiry.year} > 2017 | - -New in SeleniumLibrary 3.0. - - - - - -as_dict=False - -Returns all cookies of the current page. - -If ``as_dict`` argument evaluates as false, see `Boolean arguments` -for more details, then cookie information is returned as -a single string in format ``name1=value1; name2=value2; name3=value3``. -When ``as_dict`` argument evaluates as true, cookie information -is returned as Robot Framework dictionary format. The string format -can be used, for example, for logging purposes or in headers when -sending HTTP requests. The dictionary format is helpful when -the result can be passed to requests library's Create Session -keyword's optional cookies parameter. - -The `` as_dict`` argument is new in SeleniumLibrary 3.3 - - - - - -locator -attribute - -Returns the value of ``attribute`` from the element ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -Example: -| ${id}= | `Get Element Attribute` | css:h1 | id | - -Passing attribute name as part of the ``locator`` was removed -in SeleniumLibrary 3.2. The explicit ``attribute`` argument -should be used instead. - - - - - -locator - -Returns the number of elements matching ``locator``. - -If you wish to assert the number of matching elements, use -`Page Should Contain Element` with ``limit`` argument. Keyword will -always return an integer. - -Example: -| ${count} = | `Get Element Count` | name:div_name | -| `Should Be True` | ${count} > 2 | | - -New in SeleniumLibrary 3.0. - - - - - -locator - -Returns width and height of the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -Both width and height are returned as integers. - -Example: -| ${width} | ${height} = | `Get Element Size` | css:div#container | - - - - - -locator - -Returns the horizontal position of the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -The position is returned in pixels off the left side of the page, -as an integer. - -See also `Get Vertical Position`. - - - - - -locator -values=False - -Returns all labels or values of selection list ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -Returns visible labels by default, but values can be returned by -setting the ``values`` argument to a true value (see `Boolean -arguments`). - -Example: -| ${labels} = | `Get List Items` | mylist | | -| ${values} = | `Get List Items` | css:#example select | values=True | - -Support to return values is new in SeleniumLibrary 3.0. - - - - - - -Returns the current browser window URL. - - - - - -browser=CURRENT - -Returns and logs URLs of all windows of the selected browser. - -*Browser Scope:* - -The ``browser`` argument specifies the browser that shall return -its windows information. - -- ``browser`` can be ``index_or_alias`` like in `Switch Browser`. - -- If ``browser`` is ``CURRENT`` (default, case-insensitive) - the currently active browser is selected. - -- If ``browser`` is ``ALL`` (case-insensitive) - the window information of all windows of all opened browsers are returned. - - - - - -locator - -Returns the label of selected option from selection list ``locator``. - -If there are multiple selected options, the label of the first option -is returned. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Returns labels of selected options from selection list ``locator``. - -Starting from SeleniumLibrary 3.0, returns an empty list if there -are no selections. In earlier versions, this caused an error. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Returns the value of selected option from selection list ``locator``. - -If there are multiple selected options, the value of the first option -is returned. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Returns values of selected options from selection list ``locator``. - -Starting from SeleniumLibrary 3.0, returns an empty list if there -are no selections. In earlier versions, this caused an error. - -See the `Locating elements` section for details about the locator -syntax. - - - - - - -Gets the implicit wait value used by Selenium. - -The value is returned as a human-readable string like ``1 second``. - -See the `Implicit wait` section above for more information. - - - - - - -Gets the delay that is waited after each Selenium command. - -The value is returned as a human-readable string like ``1 second``. - -See the `Selenium Speed` section above for more information. - - - - - - -Gets the timeout that is used by various keywords. - -The value is returned as a human-readable string like ``1 second``. - -See the `Timeout` section above for more information. - - - - - - -Returns the currently active browser session id. - -New in SeleniumLibrary 3.2 - - - - - - -Returns the entire HTML source of the current page or frame. - - - - - -locator -row -column -loglevel=TRACE - -Returns contents of a table cell. - -The table is located using the ``locator`` argument and its cell -found using ``row`` and ``column``. See the `Locating elements` -section for details about the locator syntax. - -Both row and column indexes start from 1, and header and footer -rows are included in the count. It is possible to refer to rows -and columns from the end by using negative indexes so that -1 -is the last row/column, -2 is the second last, and so on. - -All ``<th>`` and ``<td>`` elements anywhere in the table are -considered to be cells. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - - - - - -locator - -Returns the text value of the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - - -Returns the title of the current page. - - - - - -locator - -Returns the value attribute of the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Returns the vertical position of the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -The position is returned in pixels off the top of the page, -as an integer. - -See also `Get Horizontal Position`. - - - - - -locator - -Returns the first WebElement matching the given ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Returns a list of WebElement objects matching the ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -Starting from SeleniumLibrary 3.0, the keyword returns an empty -list if there are no matching elements. In previous releases, the -keyword failed in this case. - - - - - -browser=CURRENT - -Returns all child window handles of the selected browser as a list. - -Can be used as a list of windows to exclude with `Select Window`. - -How to select the ``browser`` scope of this keyword, see `Get Locations`. - -Prior to SeleniumLibrary 3.0, this keyword was named `List Windows`. - - - - - -browser=CURRENT - -Returns and logs id attributes of all windows of the selected browser. - -How to select the ``browser`` scope of this keyword, see `Get Locations`. - - - - - -browser=CURRENT - -Returns and logs names of all windows of the selected browser. - -How to select the ``browser`` scope of this keyword, see `Get Locations`. - - - - - - -Returns current window position. - -The position is relative to the top left corner of the screen. Returned -values are integers. See also `Set Window Position`. - -Example: -| ${x} | ${y}= | `Get Window Position` | - - - - - -inner=False - -Returns current window width and height as integers. - -See also `Set Window Size`. - -If ``inner`` parameter is set to True, keyword returns -HTML DOM window.innerWidth and window.innerHeight properties. -See `Boolean arguments` for more details on how to set boolean -arguments. The ``inner`` is new in SeleniumLibrary 4.0. - -Example: -| ${width} | ${height}= | `Get Window Size` | | -| ${width} | ${height}= | `Get Window Size` | True | - - - - - -browser=CURRENT - -Returns and logs titles of all windows of the selected browser. - -How to select the ``browser`` scope of this keyword, see `Get Locations`. - - - - - - -Simulates the user clicking the back button on their browser. - - - - - -url - -Navigates the current browser window to the provided ``url``. - - - - - -action=ACCEPT -timeout=None - -Handles the current alert and returns its message. - -By default, the alert is accepted, but this can be controlled -with the ``action`` argument that supports the following -case-insensitive values: - -- ``ACCEPT``: Accept the alert i.e. press ``Ok``. Default. -- ``DISMISS``: Dismiss the alert i.e. press ``Cancel``. -- ``LEAVE``: Leave the alert open. - -The ``timeout`` argument specifies how long to wait for the alert -to appear. If it is not given, the global default `timeout` is used -instead. - -Examples: -| Handle Alert | | | # Accept alert. | -| Handle Alert | action=DISMISS | | # Dismiss alert. | -| Handle Alert | timeout=10 s | | # Use custom timeout and accept alert. | -| Handle Alert | DISMISS | 1 min | # Use custom timeout and dismiss alert. | -| ${message} = | Handle Alert | | # Accept alert and get its message. | -| ${message} = | Handle Alert | LEAVE | # Leave alert open and get its message. | - -New in SeleniumLibrary 3.0. - - - - - -locator -password -clear=True - -Types the given password into the text field identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. See `Input Text` for ``clear`` argument details. - -Difference compared to `Input Text` is that this keyword does not -log the given password on the INFO level. Notice that if you use -the keyword like - -| Input Password | password_field | password | - -the password is shown as a normal keyword argument. A way to avoid -that is using variables like - -| Input Password | password_field | ${PASSWORD} | - -Please notice that Robot Framework logs all arguments using -the TRACE level and tests must not be executed using level below -DEBUG if the password should not be logged in any format. - -The `clear` argument is new in SeleniumLibrary 4.0. Hiding password -logging from Selenium logs is new in SeleniumLibrary 4.2. - - - - - -locator -text -clear=True - -Types the given ``text`` into the text field identified by ``locator``. - -When ``clear`` is true, the input element is cleared before -the text is typed into the element. When false, the previous text -is not cleared from the element. Use `Input Password` if you -do not want the given ``text`` to be logged. - -If [https://github.com/SeleniumHQ/selenium/wiki/Grid2|Selenium Grid] -is used and the ``text`` argument points to a file in the file system, -then this keyword prevents the Selenium to transfer the file to the -Selenium Grid hub. Instead, this keyword will send the ``text`` string -as is to the element. If a file should be transferred to the hub and -upload should be performed, please use `Choose File` keyword. - -See the `Locating elements` section for details about the locator -syntax. See the `Boolean arguments` section how Boolean values are -handled. - -Disabling the file upload the Selenium Grid node and the `clear` -argument are new in SeleniumLibrary 4.0 - - - - - -text -action=ACCEPT -timeout=None - -Types the given ``text`` into an input field in an alert. - -The alert is accepted by default, but that behavior can be controlled -by using the ``action`` argument same way as with `Handle Alert`. - -``timeout`` specifies how long to wait for the alert to appear. -If it is not given, the global default `timeout` is used instead. - -New in SeleniumLibrary 3.0. - - - - - -locator -*expected - -Verifies selection list ``locator`` has ``expected`` options selected. - -It is possible to give expected options both as visible labels and -as values. Starting from SeleniumLibrary 3.0, mixing labels and -values is not possible. Order of the selected options is not -validated. - -If no expected options are given, validates that the list has -no selections. A more explicit alternative is using `List Should -Have No Selections`. - -See the `Locating elements` section for details about the locator -syntax. - -Examples: -| `List Selection Should Be` | gender | Female | | -| `List Selection Should Be` | interests | Test Automation | Python | - - - - - -locator - -Verifies selection list ``locator`` has no options selected. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -url -message=None - -Verifies that the current URL is exactly ``url``. - -The ``url`` argument contains the exact url that should exist in browser. - -The ``message`` argument can be used to override the default error -message. - -``message`` argument is new in SeleniumLibrary 3.2.0. - - - - - -expected -message=None - -Verifies that the current URL contains ``expected``. - -The ``expected`` argument contains the expected value in url. - -The ``message`` argument can be used to override the default error -message. - -``message`` argument is new in SeleniumLibrary 3.2.0. - - - - - -locator -x -message=None -loglevel=TRACE - -*DEPRECATED in SeleniumLibrary 4.0.*, use `Page Should Contain Element` with ``limit`` argument instead. - - - - - - -Logs and returns the current browser window URL. - - - - - -loglevel=INFO - -Logs and returns the HTML source of the current page or frame. - -The ``loglevel`` argument defines the used log level. Valid log -levels are ``WARN``, ``INFO`` (default), ``DEBUG``, ``TRACE`` -and ``NONE`` (no logging). - - - - - - -Logs and returns the title of the current page. - - - - - - -Maximizes current browser window. - - - - - -locator - -Simulates pressing the left mouse button on the element ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -The element is pressed without releasing the mouse button. - -See also the more specific keywords `Mouse Down On Image` and -`Mouse Down On Link`. - - - - - -locator - -Simulates a mouse down event on an image identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, images are searched -using ``id``, ``name``, ``src`` and ``alt``. - - - - - -locator - -Simulates a mouse down event on a link identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, links are searched -using ``id``, ``name``, ``href`` and the link text. - - - - - -locator - -Simulates moving the mouse away from the element ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Simulates hovering the mouse over the element ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Simulates releasing the left mouse button on the element ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -url=None -browser=firefox -alias=None -remote_url=False -desired_capabilities=None -ff_profile_dir=None -options=None -service_log_path=None -executable_path=None - -Opens a new browser instance to the optional ``url``. - -The ``browser`` argument specifies which browser to use. The -supported browsers are listed in the table below. The browser names -are case-insensitive and some browsers have multiple supported names. - -| = Browser = | = Name(s) = | -| Firefox | firefox, ff | -| Google Chrome | googlechrome, chrome, gc | -| Headless Firefox | headlessfirefox | -| Headless Chrome | headlesschrome | -| Internet Explorer | internetexplorer, ie | -| Edge | edge | -| Safari | safari | -| Opera | opera | -| Android | android | -| Iphone | iphone | -| PhantomJS | phantomjs | -| HTMLUnit | htmlunit | -| HTMLUnit with Javascript | htmlunitwithjs | - -To be able to actually use one of these browsers, you need to have -a matching Selenium browser driver available. See the -[https://github.com/robotframework/SeleniumLibrary#browser-drivers| -project documentation] for more details. Headless Firefox and -Headless Chrome are new additions in SeleniumLibrary 3.1.0 -and require Selenium 3.8.0 or newer. - -After opening the browser, it is possible to use optional -``url`` to navigate the browser to the desired address. - -Optional ``alias`` is an alias given for this browser instance and -it can be used for switching between browsers. When same ``alias`` -is given with two `Open Browser` keywords, the first keyword will -open a new browser, but the second one will switch to the already -opened browser and will not open a new browser. The ``alias`` -definition overrules ``browser`` definition. When same ``alias`` -is used but a different ``browser`` is defined, then switch to -a browser with same alias is done and new browser is not opened. -An alternative approach for switching is using an index returned -by this keyword. These indices start from 1, are incremented when new -browsers are opened, and reset back to 1 when `Close All Browsers` -is called. See `Switch Browser` for more information and examples. - -Optional ``remote_url`` is the URL for a -[https://github.com/SeleniumHQ/selenium/wiki/Grid2|Selenium Grid]. - -Optional ``desired_capabilities`` can be used to configure, for example, -logging preferences for a browser or a browser and operating system -when using [http://saucelabs.com|Sauce Labs]. Desired capabilities can -be given either as a Python dictionary or as a string in the format -``key1:value1,key2:value2``. -[https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities| -Selenium documentation] lists possible capabilities that can be -enabled. - -Optional ``ff_profile_dir`` is the path to the Firefox profile -directory if you wish to overwrite the default profile Selenium -uses. Notice that prior to SeleniumLibrary 3.0, the library -contained its own profile that was used by default. The -``ff_profile_dir`` can also be an instance of the -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_firefox/selenium.webdriver.firefox.firefox_profile.html|selenium.webdriver.FirefoxProfile] -. As a third option, it is possible to use `FirefoxProfile` methods -and attributes to define the profile using methods and attributes -in the same way as with ``options`` argument. Example: It is possible -to use FirefoxProfile `set_preference` to define different -profile settings. See ``options`` argument documentation in below -how to handle backslash escaping. - -Optional ``options`` argument allows defining browser specific -Selenium options. Example for Chrome, the ``options`` argument -allows defining the following -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_chrome/selenium.webdriver.chrome.options.html#selenium.webdriver.chrome.options.Options|methods and attributes] -and for Firefox these -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_firefox/selenium.webdriver.firefox.options.html?highlight=firefox#selenium.webdriver.firefox.options.Options|methods and attributes] -are available. Please note that not all browsers, supported by the -SeleniumLibrary, have Selenium options available. Therefore please -consult the Selenium documentation which browsers do support -the Selenium options. If ``browser`` argument is `android` then -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_chrome/selenium.webdriver.chrome.options.html#selenium.webdriver.chrome.options.Options|Chrome options] -is used. Selenium options are also supported, when ``remote_url`` -argument is used. - -The SeleniumLibrary ``options`` argument accepts Selenium -options in two different formats: as a string and as Python object -which is an instance of the Selenium options class. - -The string format allows defining Selenium options methods -or attributes and their arguments in Robot Framework test data. -The method and attributes names are case and space sensitive and -must match to the Selenium options methods and attributes names. -When defining a method, it must be defined in a similar way as in -python: method name, opening parenthesis, zero to many arguments -and closing parenthesis. If there is a need to define multiple -arguments for a single method, arguments must be separated with -comma, just like in Python. Example: `add_argument("--headless")` -or `add_experimental_option("key", "value")`. Attributes are -defined in a similar way as in Python: attribute name, equal sign, -and attribute value. Example, `headless=True`. Multiple methods -and attributes must be separated by a semicolon. Example: -`add_argument("--headless");add_argument("--start-maximized")`. - -Arguments allow defining Python data types and arguments are -evaluated by using Python -[https://docs.python.org/3/library/ast.html#ast.literal_eval|ast.literal_eval]. -Strings must be quoted with single or double quotes, example "value" -or 'value'. It is also possible to define other Python builtin -data types, example `True` or `None`, by not using quotes -around the arguments. - -The string format is space friendly. Usually, spaces do not alter -the defining methods or attributes. There are two exceptions. -In some Robot Framework test data formats, two or more spaces are -considered as cell separator and instead of defining a single -argument, two or more arguments may be defined. Spaces in string -arguments are not removed and are left as is. Example -`add_argument ( "--headless" )` is same as -`add_argument("--headless")`. But `add_argument(" --headless ")` is -not same same as `add_argument ( "--headless" )`, because -spaces inside of quotes are not removed. Please note that if -options string contains backslash, example a Windows OS path, -the backslash needs escaping both in Robot Framework data and -in Python side. This means single backslash must be writen using -four backslash characters. Example, Windows path: -"C:\path\to\profile" must be written as -"C:\\\\path\\\to\\\\profile". Another way to write -backslash is use Python -[https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals|raw strings] -and example write: r"C:\\path\\to\\profile". - -As last format, ``options`` argument also supports receiving -the Selenium options as Python class instance. In this case, the -instance is used as-is and the SeleniumLibrary will not convert -the instance to other formats. -For example, if the following code return value is saved to -`${options}` variable in the Robot Framework data: -| options = webdriver.ChromeOptions() -| options.add_argument('--disable-dev-shm-usage') -| return options - -Then the `${options}` variable can be used as an argument to -``options``. - -Example the ``options`` argument can be used to launch Chomium-based -applications which utilize the -[https://bitbucket.org/chromiumembedded/cef/wiki/UsingChromeDriver|Chromium Embedded Framework] -. To lauch Chomium-based application, use ``options`` to define -`binary_location` attribute and use `add_argument` method to define -`remote-debugging-port` port for the application. Once the browser -is opened, the test can interact with the embedded web-content of -the system under test. - -Optional ``service_log_path`` argument defines the name of the -file where to write the browser driver logs. If the -``service_log_path`` argument contain a marker ``{index}``, it -will be automatically replaced with unique running -index preventing files to be overwritten. Indices start's from 1, -and how they are represented can be customized using Python's -[https://docs.python.org/3/library/string.html#format-string-syntax| -format string syntax]. - -Optional ``executable_path`` argument defines the path to the driver -executable, example to a chromedriver or a geckodriver. If not defined -it is assumed the executable is in the -[https://en.wikipedia.org/wiki/PATH_(variable)|$PATH]. - -Examples: -| `Open Browser` | http://example.com | Chrome | | -| `Open Browser` | http://example.com | Firefox | alias=Firefox | -| `Open Browser` | http://example.com | Edge | remote_url=http://127.0.0.1:4444/wd/hub | -| `Open Browser` | about:blank | | | -| `Open Browser` | browser=Chrome | | | - -Alias examples: -| ${1_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Opens new browser because alias is new. | -| ${2_index} = | `Open Browser` | http://example.com | Firefox | | # Opens new browser because alias is not defined. | -| ${3_index} = | `Open Browser` | http://example.com | Chrome | alias=Chrome | # Switches to the browser with Chrome alias. | -| ${4_index} = | `Open Browser` | http://example.com | Chrome | alias=${1_index} | # Switches to the browser with Chrome alias. | -| Should Be Equal | ${1_index} | ${3_index} | | | | -| Should Be Equal | ${1_index} | ${4_index} | | | | -| Should Be Equal | ${2_index} | ${2} | | | | - -Example when using -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver_chrome/selenium.webdriver.chrome.options.html#selenium.webdriver.chrome.options.Options|Chrome options] -method: -| `Open Browser` | http://example.com | Chrome | options=add_argument("--disable-popup-blocking"); add_argument("--ignore-certificate-errors") | # Sting format. | -| ${options} = | Get Options | | | # Selenium options instance. | -| `Open Browser` | http://example.com | Chrome | options=${options} | | -| `Open Browser` | None | Chrome | options=binary_location="/path/to/binary";add_argument("remote-debugging-port=port") | # Start Chomium-based application. | -| `Open Browser` | None | Chrome | options=binary_location=r"C:\\path\\to\\binary" | # Windows OS path escaping. | - -Example for FirefoxProfile -| `Open Browser` | http://example.com | Firefox | ff_profile_dir=/path/to/profile | # Using profile from disk. | -| `Open Browser` | http://example.com | Firefox | ff_profile_dir=${FirefoxProfile_instance} | # Using instance of FirefoxProfile. | -| `Open Browser` | http://example.com | Firefox | ff_profile_dir=set_preference("key", "value");set_preference("other", "setting") | # Defining profile using FirefoxProfile mehtods. | - -If the provided configuration options are not enough, it is possible -to use `Create Webdriver` to customize browser initialization even -more. - -Applying ``desired_capabilities`` argument also for local browser is -new in SeleniumLibrary 3.1. - -Using ``alias`` to decide, is the new browser opened is new -in SeleniumLibrary 4.0. The ``options`` and ``service_log_path`` -are new in SeleniumLibrary 4.0. Support for ``ff_profile_dir`` -accepting an instance of the `selenium.webdriver.FirefoxProfile` -and support defining FirefoxProfile with methods and -attributes are new in SeleniumLibrary 4.0. - -Making ``url`` optional is new in SeleniumLibrary 4.1. - -The ``executable_path`` argument is new in SeleniumLibrary 4.2. - - - - - -locator - -Opens the context menu on the element identified by ``locator``. - - - - - -text -loglevel=TRACE - -Verifies that current page contains ``text``. - -If this keyword fails, it automatically logs the page source -using the log level specified with the optional ``loglevel`` -argument. Valid log levels are ``DEBUG``, ``INFO`` (default), -``WARN``, and ``NONE``. If the log level is ``NONE`` or below -the current active log level the source will not be logged. - - - - - -locator -message=None -loglevel=TRACE - -Verifies button ``locator`` is found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, buttons are -searched using ``id``, ``name``, and ``value``. - - - - - -locator -message=None -loglevel=TRACE - -Verifies checkbox ``locator`` is found from the current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -message=None -loglevel=TRACE -limit=None - -Verifies that element ``locator`` is found on the current page. - -See the `Locating elements` section for details about the locator -syntax. - -The ``message`` argument can be used to override the default error -message. - -The ``limit`` argument can used to define how many elements the -page should contain. When ``limit`` is ``None`` (default) page can -contain one or more elements. When limit is a number, page must -contain same number of elements. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - -Examples assumes that locator matches to two elements. -| `Page Should Contain Element` | div_name | limit=1 | # Keyword fails. | -| `Page Should Contain Element` | div_name | limit=2 | # Keyword passes. | -| `Page Should Contain Element` | div_name | limit=none | # None is considered one or more. | -| `Page Should Contain Element` | div_name | | # Same as above. | - -The ``limit`` argument is new in SeleniumLibrary 3.0. - - - - - -locator -message=None -loglevel=TRACE - -Verifies image identified by ``locator`` is found from current page. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, images are searched -using ``id``, ``name``, ``src`` and ``alt``. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - - - - - -locator -message=None -loglevel=TRACE - -Verifies link identified by ``locator`` is found from current page. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, links are searched -using ``id``, ``name``, ``href`` and the link text. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - - - - - -locator -message=None -loglevel=TRACE - -Verifies selection list ``locator`` is found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -message=None -loglevel=TRACE - -Verifies radio button ``locator`` is found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, radio buttons are -searched using ``id``, ``name`` and ``value``. - - - - - -locator -message=None -loglevel=TRACE - -Verifies text field ``locator`` is found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -text -loglevel=TRACE - -Verifies the current page does not contain ``text``. - -See `Page Should Contain` for an explanation about the ``loglevel`` -argument. - - - - - -locator -message=None -loglevel=TRACE - -Verifies button ``locator`` is not found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, buttons are -searched using ``id``, ``name``, and ``value``. - - - - - -locator -message=None -loglevel=TRACE - -Verifies checkbox ``locator`` is not found from the current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -message=None -loglevel=TRACE - -Verifies that element ``locator`` is found on the current page. - -See the `Locating elements` section for details about the locator -syntax. - -See `Page Should Contain` for an explanation about ``message`` and -``loglevel`` arguments. - - - - - -locator -message=None -loglevel=TRACE - -Verifies image identified by ``locator`` is found from current page. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, images are searched -using ``id``, ``name``, ``src`` and ``alt``. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - - - - - -locator -message=None -loglevel=TRACE - -Verifies link identified by ``locator`` is not found from current page. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, links are searched -using ``id``, ``name``, ``href`` and the link text. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - - - - - -locator -message=None -loglevel=TRACE - -Verifies selection list ``locator`` is not found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -message=None -loglevel=TRACE - -Verifies radio button ``locator`` is not found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. When using the default locator strategy, radio buttons are -searched using ``id``, ``name`` and ``value``. - - - - - -locator -message=None -loglevel=TRACE - -Verifies text field ``locator`` is not found from current page. - -See `Page Should Contain Element` for an explanation about ``message`` -and ``loglevel`` arguments. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -key - -*DEPRECATED in SeleniumLibrary 4.0.* use `Press Keys` instead. - - - - - -locator=None -*keys - -Simulates the user pressing key(s) to an element or on the active browser. - -If ``locator`` evaluates as false, see `Boolean arguments` for more -details, then the ``keys`` are sent to the currently active browser. -Otherwise element is searched and ``keys`` are send to the element -identified by the ``locator``. In later case, keyword fails if element -is not found. See the `Locating elements` section for details about -the locator syntax. - -``keys`` arguments can contain one or many strings, but it can not -be empty. ``keys`` can also be a combination of -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html|Selenium Keys] -and strings or a single Selenium Key. If Selenium Key is combined -with strings, Selenium key and strings must be separated by the -`+` character, like in `CONTROL+c`. Selenium Keys -are space and case sensitive and Selenium Keys are not parsed -inside of the string. Example AALTO, would send string `AALTO` -and `ALT` not parsed inside of the string. But `A+ALT+O` would -found Selenium ALT key from the ``keys`` argument. It also possible -to press many Selenium Keys down at the same time, example -'ALT+ARROW_DOWN`. - -If Selenium Keys are detected in the ``keys`` argument, keyword -will press the Selenium Key down, send the strings and - then release the Selenium Key. If keyword needs to send a Selenium -Key as a string, then each character must be separated with -`+` character, example `E+N+D`. - -`CTRL` is alias for -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html#selenium.webdriver.common.keys.Keys.CONTROL|Selenium CONTROL] -and ESC is alias for -[https://seleniumhq.github.io/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html#selenium.webdriver.common.keys.Keys.ESCAPE|Selenium ESCAPE] - -New in SeleniumLibrary 3.3 - -Examples: -| `Press Keys` | text_field | AAAAA | | # Sends string "AAAAA" to element. | -| `Press Keys` | None | BBBBB | | # Sends string "BBBBB" to currently active browser. | -| `Press Keys` | text_field | E+N+D | | # Sends string "END" to element. | -| `Press Keys` | text_field | XXX | YY | # Sends strings "XXX" and "YY" to element. | -| `Press Keys` | text_field | XXX+YY | | # Same as above. | -| `Press Keys` | text_field | ALT+ARROW_DOWN | | # Pressing "ALT" key down, then pressing ARROW_DOWN and then releasing both keys. | -| `Press Keys` | text_field | ALT | ARROW_DOWN | # Pressing "ALT" key and then pressing ARROW_DOWN. | -| `Press Keys` | text_field | CTRL+c | | # Pressing CTRL key down, sends string "c" and then releases CTRL key. | -| `Press Keys` | button | RETURN | | # Pressing "ENTER" key to element. | - - - - - -group_name -value - -Verifies radio button group ``group_name`` is set to ``value``. - -``group_name`` is the ``name`` of the radio button group. - - - - - -group_name - -Verifies radio button group ``group_name`` has no selection. - -``group_name`` is the ``name`` of the radio button group. - - - - - -keyword - -Sets the keyword to execute, when a SeleniumLibrary keyword fails. - -``keyword`` is the name of a keyword that will be executed if a -SeleniumLibrary keyword fails. It is possible to use any available -keyword, including user keywords or keywords from other libraries, -but the keyword must not take any arguments. - -The initial keyword to use is set when `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. - -It is possible to use string ``NOTHING`` or ``NONE``, -case-insensitively, as well as Python ``None`` to disable this -feature altogether. - -This keyword returns the name of the previously registered -failure keyword or Python ``None`` if this functionality was -previously disabled. The return value can be always used to -restore the original value later. - -Example: -| `Register Keyword To Run On Failure` | Log Source | -| ${previous kw}= | `Register Keyword To Run On Failure` | NONE | -| `Register Keyword To Run On Failure` | ${previous kw} | - -Changes in SeleniumLibrary 3.0: -- Possible to use string ``NONE`` or Python ``None`` to disable the - functionality. -- Return Python ``None`` when the functionality was disabled earlier. - In previous versions special value ``No Keyword`` was returned and - it could not be used to restore the original state. - - - - - - -Simulates user reloading page. - - - - - -strategy_name - -Removes a previously added custom location strategy. - -See `Custom locators` for information on how to create and use -custom strategies. - - - - - -locator - -Scrolls the element identified by ``locator`` into view. - -See the `Locating elements` section for details about the locator -syntax. - -New in SeleniumLibrary 3.2.0 - - - - - -locator - -Selects all options from multi-selection list ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Selects the checkbox identified by ``locator``. - -Does nothing if checkbox is already selected. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator - -Sets frame identified by ``locator`` as the current frame. - -See the `Locating elements` section for details about the locator -syntax. - -Works both with frames and iframes. Use `Unselect Frame` to cancel -the frame selection and return to the main frame. - -Example: -| `Select Frame` | top-frame | # Select frame with id or name 'top-frame' | -| `Click Link` | example | # Click link 'example' in the selected frame | -| `Unselect Frame` | | # Back to main frame. | -| `Select Frame` | //iframe[@name='xxx'] | # Select frame using xpath | - - - - - -locator -*indexes - -Selects options from selection list ``locator`` by ``indexes``. - -Indexes of list options start from 0. - -If more than one option is given for a single-selection list, -the last value will be selected. With multi-selection lists all -specified options are selected, but possible old selections are -not cleared. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -*labels - -Selects options from selection list ``locator`` by ``labels``. - -If more than one option is given for a single-selection list, -the last value will be selected. With multi-selection lists all -specified options are selected, but possible old selections are -not cleared. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -*values - -Selects options from selection list ``locator`` by ``values``. - -If more than one option is given for a single-selection list, -the last value will be selected. With multi-selection lists all -specified options are selected, but possible old selections are -not cleared. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -group_name -value - -Sets the radio button group ``group_name`` to ``value``. - -The radio button to be selected is located by two arguments: -- ``group_name`` is the name of the radio button group. -- ``value`` is the ``id`` or ``value`` attribute of the actual - radio button. - -Examples: -| `Select Radio Button` | size | XL | -| `Select Radio Button` | contact | email | - - - - - -locator=MAIN -timeout=None - -DEPRECATED in SeleniumLibrary 4.0. , use `Switch Window` instead. - - - - - -value - -Sets the implicit wait value used by Selenium. - -Same as `Set Selenium Implicit Wait` but only affects the current -browser. - - - - - -locator - -Sets the focus to the element identified by ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -Prior to SeleniumLibrary 3.0 this keyword was named `Focus`. - - - - - -path - -Sets the directory for captured screenshots. - -``path`` argument specifies the absolute path to a directory where -the screenshots should be written to. If the directory does not -exist, it will be created. The directory can also be set when -`importing` the library. If it is not configured anywhere, -screenshots are saved to the same directory where Robot Framework's -log file is written. - -If ``path`` equals to EMBED (case insensitive) and -`Capture Page Screenshot` or `capture Element Screenshot` keywords -filename argument is not changed from the default value, then -the page or element screenshot is embedded as Base64 image to -the log.html. - -The previous value is returned and can be used to restore -the original value later if needed. - -Returning the previous value is new in SeleniumLibrary 3.0. -The persist argument was removed in SeleniumLibrary 3.2 and -EMBED is new in SeleniumLibrary 4.2. - - - - - -value - -Sets the implicit wait value used by Selenium. - -The value can be given as a number that is considered to be -seconds or as a human-readable string like ``1 second``. -The previous value is returned and can be used to restore -the original value later if needed. - -This keyword sets the implicit wait for all opened browsers. -Use `Set Browser Implicit Wait` to set it only to the current -browser. - -See the `Implicit wait` section above for more information. - -Example: -| ${orig wait} = | `Set Selenium Implicit Wait` | 10 seconds | -| `Perform AJAX call that is slow` | -| `Set Selenium Implicit Wait` | ${orig wait} | - - - - - -value - -Sets the delay that is waited after each Selenium command. - -The value can be given as a number that is considered to be -seconds or as a human-readable string like ``1 second``. -The previous value is returned and can be used to restore -the original value later if needed. - -See the `Selenium Speed` section above for more information. - -Example: -| `Set Selenium Speed` | 0.5 seconds | - - - - - -value - -Sets the timeout that is used by various keywords. - -The value can be given as a number that is considered to be -seconds or as a human-readable string like ``1 second``. -The previous value is returned and can be used to restore -the original value later if needed. - -See the `Timeout` section above for more information. - -Example: -| ${orig timeout} = | `Set Selenium Timeout` | 15 seconds | -| `Open page that loads slowly` | -| `Set Selenium Timeout` | ${orig timeout} | - - - - - -x -y - -Sets window position using ``x`` and ``y`` coordinates. - -The position is relative to the top left corner of the screen, -but some browsers exclude possible task bar set by the operating -system from the calculation. The actual position may thus be -different with different browsers. - -Values can be given using strings containing numbers or by using -actual numbers. See also `Get Window Position`. - -Example: -| `Set Window Position` | 100 | 200 | - - - - - -width -height -inner=False - -Sets current windows size to given ``width`` and ``height``. - -Values can be given using strings containing numbers or by using -actual numbers. See also `Get Window Size`. - -Browsers have a limit on their minimum size. Trying to set them -smaller will cause the actual size to be bigger than the requested -size. - -If ``inner`` parameter is set to True, keyword sets the necessary -window width and height to have the desired HTML DOM _window.innerWidth_ -and _window.innerHeight_. See `Boolean arguments` for more details on how to set boolean -arguments. - -The ``inner`` argument is new since SeleniumLibrary 4.0. - -This ``inner`` argument does not support Frames. If a frame is selected, -switch to default before running this. - -Example: -| `Set Window Size` | 800 | 600 | | -| `Set Window Size` | 800 | 600 | True | - - - - - -locator -event - -Simulates ``event`` on the element identified by ``locator``. - -This keyword is useful if element has ``OnEvent`` handler that -needs to be explicitly invoked. - -See the `Locating elements` section for details about the locator -syntax. - -Prior to SeleniumLibrary 3.0 this keyword was named `Simulate`. - - - - - -locator=None - -Submits a form identified by ``locator``. - -If ``locator`` is not given, first form on the page is submitted. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -index_or_alias - -Switches between active browsers using ``index_or_alias``. - -Indices are returned by the `Open Browser` keyword and aliases can -be given to it explicitly. Indices start from 1. - -Example: -| `Open Browser` | http://google.com | ff | -| `Location Should Be` | http://google.com | | -| `Open Browser` | http://yahoo.com | ie | alias=second | -| `Location Should Be` | http://yahoo.com | | -| `Switch Browser` | 1 | # index | -| `Page Should Contain` | I'm feeling lucky | | -| `Switch Browser` | second | # alias | -| `Page Should Contain` | More Yahoo! | | -| `Close All Browsers` | | | - -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 are not sure about that, you can store the index -into a variable as below. - -| ${index} = | `Open Browser` | http://google.com | -| # Do something ... | | | -| `Switch Browser` | ${index} | | - - - - - -locator=MAIN -timeout=None -browser=CURRENT - -Switches to browser window matching ``locator``. - -If the window is found, all subsequent commands use the selected -window, until this keyword is used again. If the window is not -found, this keyword fails. The previous windows handle is returned -and can be used to switch back to it later. - -Notice that alerts should be handled with -`Handle Alert` or other alert related keywords. - -The ``locator`` can be specified using different strategies somewhat -similarly as when `locating elements` on pages. - -- By default, the ``locator`` is matched against window handle, name, - title, and URL. Matching is done in that order and the first - matching window is selected. - -- The ``locator`` can specify an explicit strategy by using the format - ``strategy:value`` (recommended) or ``strategy=value``. Supported - strategies are ``name``, ``title``, and ``url``. These matches windows - using their name, title, or URL, respectively. Additionally, ``default`` - can be used to explicitly use the default strategy explained above. - -- If the ``locator`` is ``NEW`` (case-insensitive), the latest - opened window is selected. It is an error if this is the same - as the current window. - -- If the ``locator`` is ``MAIN`` (default, case-insensitive), - the main window is selected. - -- If the ``locator`` is ``CURRENT`` (case-insensitive), nothing is - done. This effectively just returns the current window handle. - -- If the ``locator`` is not a string, it is expected to be a list - of window handles _to exclude_. Such a list of excluded windows - can be got from `Get Window Handles` before doing an action that - opens a new window. - -The ``timeout`` is used to specify how long keyword will poll to select -the new window. The ``timeout`` is new in SeleniumLibrary 3.2. - -Example: -| `Click Link` | popup1 | | # Open new window | -| `Switch Window` | example | | # Select window using default strategy | -| `Title Should Be` | Pop-up 1 | | -| `Click Button` | popup2 | | # Open another window | -| ${handle} = | `Switch Window` | NEW | # Select latest opened window | -| `Title Should Be` | Pop-up 2 | | -| `Switch Window` | ${handle} | | # Select window using handle | -| `Title Should Be` | Pop-up 1 | | -| `Switch Window` | MAIN | | # Select the main window | -| `Title Should Be` | Main | | -| ${excludes} = | `Get Window Handles` | | # Get list of current windows | -| `Click Link` | popup3 | | # Open one more window | -| `Switch Window` | ${excludes} | | # Select window using excludes | -| `Title Should Be` | Pop-up 3 | | - -The ``browser`` argument allows with ``index_or_alias`` to implicitly switch to -a specific browser when switching to a window. See `Switch Browser` - -- If the ``browser`` is ``CURRENT`` (case-insensitive), no other browser is - selected. - -*NOTE:* - -- The ``strategy:value`` syntax is only supported by SeleniumLibrary - 3.0 and newer. -- Prior to SeleniumLibrary 3.0 matching windows by name, title - and URL was case-insensitive. -- Earlier versions supported aliases ``None``, ``null`` and the - empty string for selecting the main window, and alias ``self`` - for selecting the current window. Support for these aliases was - removed in SeleniumLibrary 3.2. - - - - - -locator -row -column -expected -loglevel=TRACE - -Verifies table cell contains text ``expected``. - -See `Get Table Cell` that this keyword uses internally for -an explanation about accepted arguments. - - - - - -locator -column -expected -loglevel=TRACE - -Verifies table column contains text ``expected``. - -The table is located using the ``locator`` argument and its column -found using ``column``. See the `Locating elements` section for -details about the locator syntax. - -Column indexes start from 1. It is possible to refer to columns -from the end by using negative indexes so that -1 is the last column, --2 is the second last, and so on. - -If a table contains cells that span multiple columns, those merged -cells count as a single column. - -See `Page Should Contain Element` for an explanation about the -``loglevel`` argument. - - - - - -locator -expected -loglevel=TRACE - -Verifies table footer contains text ``expected``. - -Any ``<td>`` element inside ``<tfoot>`` element is considered to -be part of the footer. - -The table is located using the ``locator`` argument. See the -`Locating elements` section for details about the locator syntax. - -See `Page Should Contain Element` for an explanation about the -``loglevel`` argument. - - - - - -locator -expected -loglevel=TRACE - -Verifies table header contains text ``expected``. - -Any ``<th>`` element anywhere in the table is considered to be -part of the header. - -The table is located using the ``locator`` argument. See the -`Locating elements` section for details about the locator syntax. - -See `Page Should Contain Element` for an explanation about the -``loglevel`` argument. - - - - - -locator -row -expected -loglevel=TRACE - -Verifies that table row contains text ``expected``. - -The table is located using the ``locator`` argument and its column -found using ``column``. See the `Locating elements` section for -details about the locator syntax. - -Row indexes start from 1. It is possible to refer to rows -from the end by using negative indexes so that -1 is the last row, --2 is the second last, and so on. - -If a table contains cells that span multiple rows, a match -only occurs for the uppermost row of those merged cells. - -See `Page Should Contain Element` for an explanation about the -``loglevel`` argument. - - - - - -locator -expected -loglevel=TRACE - -Verifies table contains text ``expected``. - -The table is located using the ``locator`` argument. See the -`Locating elements` section for details about the locator syntax. - -See `Page Should Contain Element` for an explanation about the -``loglevel`` argument. - - - - - -locator -expected -message=None - -Verifies text area ``locator`` contains text ``expected``. - -``message`` can be used to override default error message. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -expected -message=None - -Verifies text area ``locator`` has exactly text ``expected``. - -``message`` can be used to override default error message. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -expected -message=None - -Verifies text field ``locator`` contains text ``expected``. - -``message`` can be used to override the default error message. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -expected -message=None - -Verifies text field ``locator`` has exactly text ``expected``. - -``message`` can be used to override default error message. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -title -message=None - -Verifies that the current page title equals ``title``. - -The ``message`` argument can be used to override the default error -message. - -``message`` argument is new in SeleniumLibrary 3.1. - - - - - -locator - -Unselects all options from multi-selection list ``locator``. - -See the `Locating elements` section for details about the locator -syntax. - -New in SeleniumLibrary 3.0. - - - - - -locator - -Removes the selection of checkbox identified by ``locator``. - -Does nothing if the checkbox is not selected. - -See the `Locating elements` section for details about the locator -syntax. - - - - - - -Sets the main frame as the current frame. - -In practice cancels the previous `Select Frame` call. - - - - - -locator -*indexes - -Unselects options from selection list ``locator`` by ``indexes``. - -Indexes of list options start from 0. This keyword works only with -multi-selection lists. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -*labels - -Unselects options from selection list ``locator`` by ``labels``. - -This keyword works only with multi-selection lists. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -locator -*values - -Unselects options from selection list ``locator`` by ``values``. - -This keyword works only with multi-selection lists. - -See the `Locating elements` section for details about the locator -syntax. - - - - - -condition -timeout=None -error=None - -Waits until ``condition`` is true or ``timeout`` expires. - -The condition can be arbitrary JavaScript expression but it -must return a value to be evaluated. See `Execute JavaScript` for -information about accessing content on pages. - -Fails if the timeout expires before the condition becomes true. See -the `Timeouts` section for more information about using timeouts -and their default value. - -``error`` can be used to override the default error message. - -Examples: -| `Wait For Condition` | return document.title == "New Title" | -| `Wait For Condition` | return jQuery.active == 0 | -| `Wait For Condition` | style = document.querySelector('h1').style; return style.background == "red" && style.color == "white" | - - - - - -locator -text -timeout=None -error=None - -Waits until the element ``locator`` contains ``text``. - -Fails if ``timeout`` expires before the text appears. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - - -locator -text -timeout=None -error=None - -Waits until the element ``locator`` does not contain ``text``. - -Fails if ``timeout`` expires before the text disappears. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - - -locator -timeout=None -error=None - -Waits until the element ``locator`` is enabled. - -Element is considered enabled if it is not disabled nor read-only. - -Fails if ``timeout`` expires before the element is enabled. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - -Considering read-only elements to be disabled is a new feature -in SeleniumLibrary 3.0. - - - - - -locator -timeout=None -error=None - -Waits until the element ``locator`` is not visible. - -Fails if ``timeout`` expires before the element is not visible. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - - -locator -timeout=None -error=None - -Waits until the element ``locator`` is visible. - -Fails if ``timeout`` expires before the element is visible. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - - -expected -timeout=None -message=None - -Waits until the current URL contains ``expected``. - -The ``expected`` argument contains the expected value in url. - -Fails if ``timeout`` expires before the location contains. See -the `Timeouts` section for more information about using timeouts -and their default value. - -The ``message`` argument can be used to override the default error -message. - -New in SeleniumLibrary 4.0 - - - - - -location -timeout=None -message=None - -Waits until the current URL does not contains ``location``. - -The ``location`` argument contains value not expected in url. - -Fails if ``timeout`` expires before the location not contains. See -the `Timeouts` section for more information about using timeouts -and their default value. - -The ``message`` argument can be used to override the default error -message. - -New in SeleniumLibrary 4.3 - - - - - -expected -timeout=None -message=None - -Waits until the current URL is ``expected``. - -The ``expected`` argument is the expected value in url. - -Fails if ``timeout`` expires before the location is. See -the `Timeouts` section for more information about using timeouts -and their default value. - -The ``message`` argument can be used to override the default error -message. - -New in SeleniumLibrary 4.0 - - - - - -location -timeout=None -message=None - -Waits until the current URL is not ``location``. - -The ``location`` argument is the unexpected value in url. - -Fails if ``timeout`` expires before the location is not. See -the `Timeouts` section for more information about using timeouts -and their default value. - -The ``message`` argument can be used to override the default error -message. - -New in SeleniumLibrary 4.3 - - - - - -text -timeout=None -error=None - -Waits until ``text`` appears on the current page. - -Fails if ``timeout`` expires before the text appears. See -the `Timeouts` section for more information about using timeouts -and their default value. - -``error`` can be used to override the default error message. - - - - - -locator -timeout=None -error=None - -Waits until the element ``locator`` appears on the current page. - -Fails if ``timeout`` expires before the element appears. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - - -text -timeout=None -error=None - -Waits until ``text`` disappears from the current page. - -Fails if ``timeout`` expires before the text disappears. See -the `Timeouts` section for more information about using timeouts -and their default value. - -``error`` can be used to override the default error message. - - - - - -locator -timeout=None -error=None - -Waits until the element ``locator`` disappears from the current page. - -Fails if ``timeout`` expires before the element disappears. See -the `Timeouts` section for more information about using timeouts and -their default value and the `Locating elements` section for details -about the locator syntax. - -``error`` can be used to override the default error message. - - - - diff --git a/libspecs/String.libspec b/libspecs/String.libspec deleted file mode 100644 index e36e617..0000000 --- a/libspecs/String.libspec +++ /dev/null @@ -1,722 +0,0 @@ - - -3.1.2 -global -yes -A test library for string manipulation and verification. - -``String`` is Robot Framework's standard library for manipulating -strings (e.g. `Replace String Using Regexp`, `Split To Lines`) and -verifying their contents (e.g. `Should Be String`). - -Following keywords from ``BuiltIn`` library can also be used with strings: - -- `Catenate` -- `Get Length` -- `Length Should Be` -- `Should (Not) Be Empty` -- `Should (Not) Be Equal (As Strings/Integers/Numbers)` -- `Should (Not) Match (Regexp)` -- `Should (Not) Contain` -- `Should (Not) Start With` -- `Should (Not) End With` -- `Convert To String` -- `Convert To Bytes` - - -string - -Converts string to lowercase. - -Examples: -| ${str1} = | Convert To Lowercase | ABC | -| ${str2} = | Convert To Lowercase | 1A2c3D | -| Should Be Equal | ${str1} | abc | -| Should Be Equal | ${str2} | 1a2c3d | - - - - - -string - -Converts string to uppercase. - -Examples: -| ${str1} = | Convert To Uppercase | abc | -| ${str2} = | Convert To Uppercase | 1a2C3d | -| Should Be Equal | ${str1} | ABC | -| Should Be Equal | ${str2} | 1A2C3D | - - - - - -bytes -encoding -errors=strict - -Decodes the given ``bytes`` to a Unicode string using the given ``encoding``. - -``errors`` argument controls what to do if decoding some bytes fails. -All values accepted by ``decode`` method in Python are valid, but in -practice the following values are most useful: - -- ``strict``: fail if characters cannot be decoded (default) -- ``ignore``: ignore characters that cannot be decoded -- ``replace``: replace characters that cannot be decoded with - a replacement character - -Examples: -| ${string} = | Decode Bytes To String | ${bytes} | UTF-8 | -| ${string} = | Decode Bytes To String | ${bytes} | ASCII | errors=ignore | - -Use `Encode String To Bytes` if you need to convert Unicode strings to -byte strings, and `Convert To String` in ``BuiltIn`` if you need to -convert arbitrary objects to Unicode strings. - - - - - -string -encoding -errors=strict - -Encodes the given Unicode ``string`` to bytes using the given ``encoding``. - -``errors`` argument controls what to do if encoding some characters fails. -All values accepted by ``encode`` method in Python are valid, but in -practice the following values are most useful: - -- ``strict``: fail if characters cannot be encoded (default) -- ``ignore``: ignore characters that cannot be encoded -- ``replace``: replace characters that cannot be encoded with - a replacement character - -Examples: -| ${bytes} = | Encode String To Bytes | ${string} | UTF-8 | -| ${bytes} = | Encode String To Bytes | ${string} | ASCII | errors=ignore | - -Use `Convert To Bytes` in ``BuiltIn`` if you want to create bytes based -on character or integer sequences. Use `Decode Bytes To String` if you -need to convert byte strings to Unicode strings and `Convert To String` -in ``BuiltIn`` if you need to convert arbitrary objects to Unicode. - - - - - -string -marker - -Returns contents of the ``string`` before the first occurrence of ``marker``. - -If the ``marker`` is not found, whole string is returned. - -See also `Fetch From Right`, `Split String` and `Split String -From Right`. - - - - - -string -marker - -Returns contents of the ``string`` after the last occurrence of ``marker``. - -If the ``marker`` is not found, whole string is returned. - -See also `Fetch From Left`, `Split String` and `Split String -From Right`. - - - - - -template -*positional -**named - -Formats a ``template`` using the given ``positional`` and ``named`` arguments. - -The template can be either be a string or an absolute path to -an existing file. In the latter case the file is read and its contents -are used as the template. If the template file contains non-ASCII -characters, it must be encoded using UTF-8. - -The template is formatted using Python's -[https://docs.python.org/library/string.html#format-string-syntax|format -string syntax]. Placeholders are marked using ``{}`` with possible -field name and format specification inside. Literal curly braces -can be inserted by doubling them like `{{` and `}}`. - -Examples: -| ${to} = | Format String | To: {} <{}> | ${user} | ${email} | -| ${to} = | Format String | To: {name} <{email}> | name=${name} | email=${email} | -| ${to} = | Format String | To: {user.name} <{user.email}> | user=${user} | -| ${xx} = | Format String | {:*^30} | centered | -| ${yy} = | Format String | {0:{width}{base}} | ${42} | base=X | width=10 | -| ${zz} = | Format String | ${CURDIR}/template.txt | positional | named=value | - -New in Robot Framework 3.1. - - - - - -length=8 -chars=[LETTERS][NUMBERS] - -Generates a string with a desired ``length`` from the given ``chars``. - -The population sequence ``chars`` contains the characters to use -when generating the random string. It can contain any -characters, and it is possible to use special markers -explained in the table below: - -| = Marker = | = Explanation = | -| ``[LOWER]`` | Lowercase ASCII characters from ``a`` to ``z``. | -| ``[UPPER]`` | Uppercase ASCII characters from ``A`` to ``Z``. | -| ``[LETTERS]`` | Lowercase and uppercase ASCII characters. | -| ``[NUMBERS]`` | Numbers from 0 to 9. | - -Examples: -| ${ret} = | Generate Random String | -| ${low} = | Generate Random String | 12 | [LOWER] | -| ${bin} = | Generate Random String | 8 | 01 | -| ${hex} = | Generate Random String | 4 | [NUMBERS]abcdef | - - - - - -string -line_number - -Returns the specified line from the given ``string``. - -Line numbering starts from 0 and it is possible to use -negative indices to refer to lines from the end. The line is -returned without the newline character. - -Examples: -| ${first} = | Get Line | ${string} | 0 | -| ${2nd last} = | Get Line | ${string} | -2 | - -Use `Split To Lines` if all lines are needed. - - - - - -string - -Returns and logs the number of lines in the given string. - - - - - -string -pattern -case_insensitive=False - -Returns lines of the given ``string`` that contain the ``pattern``. - -The ``pattern`` is always considered to be a normal string, not a glob -or regexp pattern. A line matches if the ``pattern`` is found anywhere -on it. - -The match is case-sensitive by default, but giving ``case_insensitive`` -a true value makes it case-insensitive. The value is considered true -if it is a non-empty string that is not equal to ``false``, ``none`` or -``no``. If the value is not a string, its truth value is got directly -in Python. Considering ``none`` false is new in RF 3.0.3. - -Lines are returned as one string catenated back together with -newlines. Possible trailing newline is never returned. The -number of matching lines is automatically logged. - -Examples: -| ${lines} = | Get Lines Containing String | ${result} | An example | -| ${ret} = | Get Lines Containing String | ${ret} | FAIL | case-insensitive | - -See `Get Lines Matching Pattern` and `Get Lines Matching Regexp` -if you need more complex pattern matching. - - - - - -string -pattern -case_insensitive=False - -Returns lines of the given ``string`` that match the ``pattern``. - -The ``pattern`` is a _glob pattern_ where: -| ``*`` | matches everything | -| ``?`` | matches any single character | -| ``[chars]`` | matches any character inside square brackets (e.g. ``[abc]`` matches either ``a``, ``b`` or ``c``) | -| ``[!chars]`` | matches any character not inside square brackets | - -A line matches only if it matches the ``pattern`` fully. - -The match is case-sensitive by default, but giving ``case_insensitive`` -a true value makes it case-insensitive. The value is considered true -if it is a non-empty string that is not equal to ``false``, ``none`` or -``no``. If the value is not a string, its truth value is got directly -in Python. Considering ``none`` false is new in RF 3.0.3. - -Lines are returned as one string catenated back together with -newlines. Possible trailing newline is never returned. The -number of matching lines is automatically logged. - -Examples: -| ${lines} = | Get Lines Matching Pattern | ${result} | Wild???? example | -| ${ret} = | Get Lines Matching Pattern | ${ret} | FAIL: * | case_insensitive=true | - -See `Get Lines Matching Regexp` if you need more complex -patterns and `Get Lines Containing String` if searching -literal strings is enough. - - - - - -string -pattern -partial_match=False - -Returns lines of the given ``string`` that match the regexp ``pattern``. - -See `BuiltIn.Should Match Regexp` for more information about -Python regular expression syntax in general and how to use it -in Robot Framework test data in particular. - -By default lines match only if they match the pattern fully, but -partial matching can be enabled by giving the ``partial_match`` -argument a true value. The value is considered true -if it is a non-empty string that is not equal to ``false``, ``none`` or -``no``. If the value is not a string, its truth value is got directly -in Python. Considering ``none`` false is new in RF 3.0.3. - -If the pattern is empty, it matches only empty lines by default. -When partial matching is enabled, empty pattern matches all lines. - -Notice that to make the match case-insensitive, you need to prefix -the pattern with case-insensitive flag ``(?i)``. - -Lines are returned as one string concatenated back together with -newlines. Possible trailing newline is never returned. The -number of matching lines is automatically logged. - -Examples: -| ${lines} = | Get Lines Matching Regexp | ${result} | Reg\\w{3} example | -| ${lines} = | Get Lines Matching Regexp | ${result} | Reg\\w{3} example | partial_match=true | -| ${ret} = | Get Lines Matching Regexp | ${ret} | (?i)FAIL: .* | - -See `Get Lines Matching Pattern` and `Get Lines Containing -String` if you do not need full regular expression powers (and -complexity). - -``partial_match`` argument is new in Robot Framework 2.9. In earlier - versions exact match was always required. - - - - - -string -pattern -*groups - -Returns a list of all non-overlapping matches in the given string. - -``string`` is the string to find matches from and ``pattern`` is the -regular expression. See `BuiltIn.Should Match Regexp` for more -information about Python regular expression syntax in general and how -to use it in Robot Framework test data in particular. - -If no groups are used, the returned list contains full matches. If one -group is used, the list contains only contents of that group. If -multiple groups are used, the list contains tuples that contain -individual group contents. All groups can be given as indexes (starting -from 1) and named groups also as names. - -Examples: -| ${no match} = | Get Regexp Matches | the string | xxx | -| ${matches} = | Get Regexp Matches | the string | t.. | -| ${one group} = | Get Regexp Matches | the string | t(..) | 1 | -| ${named group} = | Get Regexp Matches | the string | t(?P<name>..) | name | -| ${two groups} = | Get Regexp Matches | the string | t(.)(.) | 1 | 2 | -=> -| ${no match} = [] -| ${matches} = ['the', 'tri'] -| ${one group} = ['he', 'ri'] -| ${named group} = ['he', 'ri'] -| ${two groups} = [('h', 'e'), ('r', 'i')] - -New in Robot Framework 2.9. - - - - - -string -start -end=None - -Returns a substring from ``start`` index to ``end`` index. - -The ``start`` index is inclusive and ``end`` is exclusive. -Indexing starts from 0, and it is possible to use -negative indices to refer to characters from the end. - -Examples: -| ${ignore first} = | Get Substring | ${string} | 1 | | -| ${ignore last} = | Get Substring | ${string} | | -1 | -| ${5th to 10th} = | Get Substring | ${string} | 4 | 10 | -| ${first two} = | Get Substring | ${string} | | 1 | -| ${last two} = | Get Substring | ${string} | -2 | | - - - - - -string -*removables - -Removes all ``removables`` from the given ``string``. - -``removables`` are used as literal strings. Each removable will be -matched to a temporary string from which preceding removables have -been already removed. See second example below. - -Use `Remove String Using Regexp` if more powerful pattern matching is -needed. If only a certain number of matches should be removed, -`Replace String` or `Replace String Using Regexp` can be used. - -A modified version of the string is returned and the original -string is not altered. - -Examples: -| ${str} = | Remove String | Robot Framework | work | -| Should Be Equal | ${str} | Robot Frame | -| ${str} = | Remove String | Robot Framework | o | bt | -| Should Be Equal | ${str} | R Framewrk | - - - - - -string -*patterns - -Removes ``patterns`` from the given ``string``. - -This keyword is otherwise identical to `Remove String`, but -the ``patterns`` to search for are considered to be a regular -expression. See `Replace String Using Regexp` for more information -about the regular expression syntax. That keyword can also be -used if there is a need to remove only a certain number of -occurrences. - - - - - -string -search_for -replace_with -count=-1 - -Replaces ``search_for`` in the given ``string`` with ``replace_with``. - -``search_for`` is used as a literal string. See `Replace String -Using Regexp` if more powerful pattern matching is needed. -If you need to just remove a string see `Remove String`. - -If the optional argument ``count`` is given, only that many -occurrences from left are replaced. Negative ``count`` means -that all occurrences are replaced (default behaviour) and zero -means that nothing is done. - -A modified version of the string is returned and the original -string is not altered. - -Examples: -| ${str} = | Replace String | Hello, world! | world | tellus | -| Should Be Equal | ${str} | Hello, tellus! | | | -| ${str} = | Replace String | Hello, world! | l | ${EMPTY} | count=1 | -| Should Be Equal | ${str} | Helo, world! | | | - - - - - -string -pattern -replace_with -count=-1 - -Replaces ``pattern`` in the given ``string`` with ``replace_with``. - -This keyword is otherwise identical to `Replace String`, but -the ``pattern`` to search for is considered to be a regular -expression. See `BuiltIn.Should Match Regexp` for more -information about Python regular expression syntax in general -and how to use it in Robot Framework test data in particular. - -If you need to just remove a string see `Remove String Using Regexp`. - -Examples: -| ${str} = | Replace String Using Regexp | ${str} | 20\\d\\d-\\d\\d-\\d\\d | <DATE> | -| ${str} = | Replace String Using Regexp | ${str} | (Hello|Hi) | ${EMPTY} | count=1 | - - - - - -item -msg=None - -Fails if the given ``item`` is not a byte string. - -Use `Should Be Unicode String` if you want to verify the ``item`` is a -Unicode string, or `Should Be String` if both Unicode and byte strings -are fine. See `Should Be String` for more details about Unicode strings -and byte strings. - -The default error message can be overridden with the optional -``msg`` argument. - - - - - -string -msg=None - -Fails if the given ``string`` is not in lowercase. - -For example, ``'string'`` and ``'with specials!'`` would pass, and -``'String'``, ``''`` and ``' '`` would fail. - -The default error message can be overridden with the optional -``msg`` argument. - -See also `Should Be Uppercase` and `Should Be Titlecase`. - - - - - -item -msg=None - -Fails if the given ``item`` is not a string. - -With Python 2, except with IronPython, this keyword passes regardless -is the ``item`` a Unicode string or a byte string. Use `Should Be -Unicode String` or `Should Be Byte String` if you want to restrict -the string type. Notice that with Python 2, except with IronPython, -``'string'`` creates a byte string and ``u'unicode'`` must be used to -create a Unicode string. - -With Python 3 and IronPython, this keyword passes if the string is -a Unicode string but fails if it is bytes. Notice that with both -Python 3 and IronPython, ``'string'`` creates a Unicode string, and -``b'bytes'`` must be used to create a byte string. - -The default error message can be overridden with the optional -``msg`` argument. - - - - - -string -msg=None - -Fails if given ``string`` is not title. - -``string`` is a titlecased string if there is at least one -character in it, uppercase characters only follow uncased -characters and lowercase characters only cased ones. - -For example, ``'This Is Title'`` would pass, and ``'Word In UPPER'``, -``'Word In lower'``, ``''`` and ``' '`` would fail. - -The default error message can be overridden with the optional -``msg`` argument. - -See also `Should Be Uppercase` and `Should Be Lowercase`. - - - - - -item -msg=None - -Fails if the given ``item`` is not a Unicode string. - -Use `Should Be Byte String` if you want to verify the ``item`` is a -byte string, or `Should Be String` if both Unicode and byte strings -are fine. See `Should Be String` for more details about Unicode -strings and byte strings. - -The default error message can be overridden with the optional -``msg`` argument. - - - - - -string -msg=None - -Fails if the given ``string`` is not in uppercase. - -For example, ``'STRING'`` and ``'WITH SPECIALS!'`` would pass, and -``'String'``, ``''`` and ``' '`` would fail. - -The default error message can be overridden with the optional -``msg`` argument. - -See also `Should Be Titlecase` and `Should Be Lowercase`. - - - - - -item -msg=None - -Fails if the given ``item`` is a string. - -See `Should Be String` for more details about Unicode strings and byte -strings. - -The default error message can be overridden with the optional -``msg`` argument. - - - - - -string -separator=None -max_split=-1 - -Splits the ``string`` using ``separator`` as a delimiter string. - -If a ``separator`` is not given, any whitespace string is a -separator. In that case also possible consecutive whitespace -as well as leading and trailing whitespace is ignored. - -Split words are returned as a list. If the optional -``max_split`` is given, at most ``max_split`` splits are done, and -the returned list will have maximum ``max_split + 1`` elements. - -Examples: -| @{words} = | Split String | ${string} | -| @{words} = | Split String | ${string} | ,${SPACE} | -| ${pre} | ${post} = | Split String | ${string} | :: | 1 | - -See `Split String From Right` if you want to start splitting -from right, and `Fetch From Left` and `Fetch From Right` if -you only want to get first/last part of the string. - - - - - -string -separator=None -max_split=-1 - -Splits the ``string`` using ``separator`` starting from right. - -Same as `Split String`, but splitting is started from right. This has -an effect only when ``max_split`` is given. - -Examples: -| ${first} | ${rest} = | Split String | ${string} | - | 1 | -| ${rest} | ${last} = | Split String From Right | ${string} | - | 1 | - - - - - -string - -Splits the given ``string`` to characters. - -Example: -| @{characters} = | Split String To Characters | ${string} | - - - - - -string -start=0 -end=None - -Splits the given string to lines. - -It is possible to get only a selection of lines from ``start`` -to ``end`` so that ``start`` index is inclusive and ``end`` is -exclusive. Line numbering starts from 0, and it is possible to -use negative indices to refer to lines from the end. - -Lines are returned without the newlines. The number of -returned lines is automatically logged. - -Examples: -| @{lines} = | Split To Lines | ${manylines} | | | -| @{ignore first} = | Split To Lines | ${manylines} | 1 | | -| @{ignore last} = | Split To Lines | ${manylines} | | -1 | -| @{5th to 10th} = | Split To Lines | ${manylines} | 4 | 10 | -| @{first two} = | Split To Lines | ${manylines} | | 1 | -| @{last two} = | Split To Lines | ${manylines} | -2 | | - -Use `Get Line` if you only need to get a single line. - - - - - -string -mode=both -characters=None - -Remove leading and/or trailing whitespaces from the given string. - -``mode`` is either ``left`` to remove leading characters, ``right`` to -remove trailing characters, ``both`` (default) to remove the -characters from both sides of the string or ``none`` to return the -unmodified string. - -If the optional ``characters`` is given, it must be a string and the -characters in the string will be stripped in the string. Please note, -that this is not a substring to be removed but a list of characters, -see the example below. - -Examples: -| ${stripped}= | Strip String | ${SPACE}Hello${SPACE} | | -| Should Be Equal | ${stripped} | Hello | | -| ${stripped}= | Strip String | ${SPACE}Hello${SPACE} | mode=left | -| Should Be Equal | ${stripped} | Hello${SPACE} | | -| ${stripped}= | Strip String | aabaHelloeee | characters=abe | -| Should Be Equal | ${stripped} | Hello | | - -New in Robot Framework 3.0. - - - - diff --git a/libspecs/Telnet.libspec b/libspecs/Telnet.libspec deleted file mode 100644 index 25e70e8..0000000 --- a/libspecs/Telnet.libspec +++ /dev/null @@ -1,744 +0,0 @@ - - -3.1.2 -test suite -yes -A test library providing communication over Telnet connections. - -``Telnet`` is Robot Framework's standard library that makes it possible to -connect to Telnet servers and execute commands on the opened connections. - -== Table of contents == - -- `Connections` -- `Writing and reading` -- `Configuration` -- `Terminal emulation` -- `Logging` -- `Time string format` -- `Boolean arguments` -- `Importing` -- `Shortcuts` -- `Keywords` - -= Connections = - -The first step of using ``Telnet`` is opening a connection with `Open -Connection` keyword. Typically the next step is logging in with `Login` -keyword, and in the end the opened connection can be closed with `Close -Connection`. - -It is possible to open multiple connections and switch the active one -using `Switch Connection`. `Close All Connections` can be used to close -all the connections, which is especially useful in suite teardowns to -guarantee that all connections are always closed. - -= Writing and reading = - -After opening a connection and possibly logging in, commands can be -executed or text written to the connection for other reasons using `Write` -and `Write Bare` keywords. The main difference between these two is that -the former adds a [#Configuration|configurable newline] after the text -automatically. - -After writing something to the connection, the resulting output can be -read using `Read`, `Read Until`, `Read Until Regexp`, and `Read Until -Prompt` keywords. Which one to use depends on the context, but the latest -one is often the most convenient. - -As a convenience when running a command, it is possible to use `Execute -Command` that simply uses `Write` and `Read Until Prompt` internally. -`Write Until Expected Output` is useful if you need to wait until writing -something produces a desired output. - -Written and read text is automatically encoded/decoded using a -[#Configuration|configured encoding]. - -The ANSI escape codes, like cursor movement and color codes, are -normally returned as part of the read operation. If an escape code occurs -in middle of a search pattern it may also prevent finding the searched -string. `Terminal emulation` can be used to process these -escape codes as they would be if a real terminal would be in use. - -= Configuration = - -Many aspects related the connections can be easily configured either -globally or per connection basis. Global configuration is done when -[#Importing|library is imported], and these values can be overridden per -connection by `Open Connection` or with setting specific keywords -`Set Timeout`, `Set Newline`, `Set Prompt`, `Set Encoding`, -`Set Default Log Level` and `Set Telnetlib Log Level`. - -Values of ``environ_user``, ``window_size``, ``terminal_emulation``, and -``terminal_type`` can not be changed after opening the connection. - -== Timeout == - -Timeout defines how long is the maximum time to wait when reading -output. It is used internally by `Read Until`, `Read Until Regexp`, -`Read Until Prompt`, and `Login` keywords. The default value is 3 seconds. - -== Connection Timeout == - -Connection Timeout defines how long is the maximum time to wait when -opening the telnet connection. It is used internally by `Open Connection`. -The default value is the system global default timeout. - -New in Robot Framework 2.9.2. - -== Newline == - -Newline defines which line separator `Write` keyword should use. The -default value is ``CRLF`` that is typically used by Telnet connections. - -Newline can be given either in escaped format using ``\n`` and ``\r`` or -with special ``LF`` and ``CR`` syntax. - -Examples: -| `Set Newline` | \n | -| `Set Newline` | CRLF | - -== Prompt == - -Often the easiest way to read the output of a command is reading all -the output until the next prompt with `Read Until Prompt`. It also makes -it easier, and faster, to verify did `Login` succeed. - -Prompt can be specified either as a normal string or a regular expression. -The latter is especially useful if the prompt changes as a result of -the executed commands. Prompt can be set to be a regular expression -by giving ``prompt_is_regexp`` argument a true value (see `Boolean -arguments`). - -Examples: -| `Open Connection` | lolcathost | prompt=$ | -| `Set Prompt` | (> |# ) | prompt_is_regexp=true | - -== Encoding == - -To ease handling text containing non-ASCII characters, all written text is -encoded and read text decoded by default. The default encoding is UTF-8 -that works also with ASCII. Encoding can be disabled by using a special -encoding value ``NONE``. This is mainly useful if you need to get the bytes -received from the connection as-is. - -Notice that when writing to the connection, only Unicode strings are -encoded using the defined encoding. Byte strings are expected to be already -encoded correctly. Notice also that normal text in test data is passed to -the library as Unicode and you need to use variables to use bytes. - -It is also possible to configure the error handler to use if encoding or -decoding characters fails. Accepted values are the same that encode/decode -functions in Python strings accept. In practice the following values are -the most useful: - -- ``ignore``: ignore characters that cannot be encoded (default) -- ``strict``: fail if characters cannot be encoded -- ``replace``: replace characters that cannot be encoded with a replacement - character - -Examples: -| `Open Connection` | lolcathost | encoding=Latin1 | encoding_errors=strict | -| `Set Encoding` | ISO-8859-15 | -| `Set Encoding` | errors=ignore | - -== Default log level == - -Default log level specifies the log level keywords use for `logging` unless -they are given an explicit log level. The default value is ``INFO``, and -changing it, for example, to ``DEBUG`` can be a good idea if there is lot -of unnecessary output that makes log files big. - -== Terminal type == - -By default the Telnet library does not negotiate any specific terminal type -with the server. If a specific terminal type, for example ``vt100``, is -desired, the terminal type can be configured in `importing` and with -`Open Connection`. - -== Window size == - -Window size for negotiation with the server can be configured when -`importing` the library and with `Open Connection`. - -== USER environment variable == - -Telnet protocol allows the ``USER`` environment variable to be sent when -connecting to the server. On some servers it may happen that there is no -login prompt, and on those cases this configuration option will allow still -to define the desired username. The option ``environ_user`` can be used in -`importing` and with `Open Connection`. - -= Terminal emulation = - -Telnet library supports terminal -emulation with [http://pyte.readthedocs.io|Pyte]. Terminal emulation -will process the output in a virtual screen. This means that ANSI escape -codes, like cursor movements, and also control characters, like -carriage returns and backspaces, have the same effect on the result as they -would have on a normal terminal screen. For example the sequence -``acdc\x1b[3Dbba`` will result in output ``abba``. - -Terminal emulation is taken into use by giving ``terminal_emulation`` -argument a true value (see `Boolean arguments`) either in the library -initialization or with `Open Connection`. - -As Pyte approximates vt-style terminal, you may also want to set the -terminal type as ``vt100``. We also recommend that you increase the window -size, as the terminal emulation will break all lines that are longer than -the window row length. - -When terminal emulation is used, the `newline` and `encoding` can not be -changed anymore after opening the connection. - -Examples: -| `Open Connection` | lolcathost | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 | - -As a prerequisite for using terminal emulation, you need to have Pyte -installed. Due to backwards incompatible changes in Pyte, different -Robot Framework versions support different Pyte versions: - -- Pyte 0.6 and newer are supported by Robot Framework 3.0.3. - Latest Pyte version can be installed (or upgraded) with - ``pip install --upgrade pyte``. -- Pyte 0.5.2 and older are supported by Robot Framework 3.0.2 and earlier. - Pyte 0.5.2 can be installed with ``pip install pyte==0.5.2``. - -= Logging = - -All keywords that read something log the output. These keywords take the -log level to use as an optional argument, and if no log level is specified -they use the [#Configuration|configured] default value. - -The valid log levels to use are ``TRACE``, ``DEBUG``, ``INFO`` (default), -and ``WARN``. Levels below ``INFO`` are not shown in log files by default -whereas warnings are shown more prominently. - -The [http://docs.python.org/library/telnetlib.html|telnetlib module] -used by this library has a custom logging system for logging content it -sends and receives. By default these messages are written using ``TRACE`` -level, but the level is configurable with the ``telnetlib_log_level`` -option either in the library initialization, to the `Open Connection` -or by using the `Set Telnetlib Log Level` keyword to the active -connection. Special level ``NONE`` con be used to disable the logging -altogether. - -= Time string format = - -Timeouts and other times used must be given as a time string using format -like ``15 seconds`` or ``1min 10s``. If the timeout is given as just -a number, for example, ``10`` or ``1.5``, it is considered to be seconds. -The time string format is described in more detail in an appendix of -[http://robotframework.org/robotframework/#user-guide|Robot Framework User Guide]. - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Other strings are considered true regardless -their value, and other argument types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Open Connection` | lolcathost | terminal_emulation=True | # Strings are generally true. | -| `Open Connection` | lolcathost | terminal_emulation=yes | # Same as the above. | -| `Open Connection` | lolcathost | terminal_emulation=${TRUE} | # Python ``True`` is true. | -| `Open Connection` | lolcathost | terminal_emulation=${42} | # Numbers other than 0 are true. | - -False examples: -| `Open Connection` | lolcathost | terminal_emulation=False | # String ``false`` is false. | -| `Open Connection` | lolcathost | terminal_emulation=no | # Also string ``no`` is false. | -| `Open Connection` | lolcathost | terminal_emulation=${EMPTY} | # Empty string is false. | -| `Open Connection` | lolcathost | terminal_emulation=${FALSE} | # Python ``False`` is false. | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - - -timeout=3 seconds -newline=CRLF -prompt=None -prompt_is_regexp=False -encoding=UTF-8 -encoding_errors=ignore -default_log_level=INFO -window_size=None -environ_user=None -terminal_emulation=False -terminal_type=None -telnetlib_log_level=TRACE -connection_timeout=None - -Telnet library can be imported with optional configuration parameters. - -Configuration parameters are used as default values when new -connections are opened with `Open Connection` keyword. They can also be -overridden after opening the connection using the `Set ...` `keywords`. -See these keywords as well as `Configuration`, `Terminal emulation` and -`Logging` sections above for more information about these parameters -and their possible values. - -See `Time string format` and `Boolean arguments` sections for -information about using arguments accepting times and Boolean values, -respectively. - -Examples (use only one of these): -| = Setting = | = Value = | = Value = | = Value = | = Value = | = Comment = | -| Library | Telnet | | | | # default values | -| Library | Telnet | 5 seconds | | | # set only timeout | -| Library | Telnet | newline=LF | encoding=ISO-8859-1 | | # set newline and encoding using named arguments | -| Library | Telnet | prompt=$ | | | # set prompt | -| Library | Telnet | prompt=(> |# ) | prompt_is_regexp=yes | | # set prompt as a regular expression | -| Library | Telnet | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 | # use terminal emulation with defined window size and terminal type | -| Library | Telnet | telnetlib_log_level=NONE | | | # disable logging messages from the underlying telnetlib | - - - - - - -Closes all open connections and empties the connection cache. - -If multiple connections are opened, this keyword should be used in -a test or suite teardown to make sure that all connections are closed. -It is not an error is some of the connections have already been closed -by `Close Connection`. - -After this keyword, new indexes returned by `Open Connection` -keyword are reset to 1. - - - - - -loglevel=None - -Closes the current Telnet connection. - -Remaining output in the connection is read, logged, and returned. -It is not an error to close an already closed connection. - -Use `Close All Connections` if you want to make sure all opened -connections are closed. - -See `Logging` section for more information about log levels. - - - - - -command -loglevel=None -strip_prompt=False - -Executes the given ``command`` and reads, logs, and returns everything until the prompt. - -This keyword requires the prompt to be [#Configuration|configured] -either in `importing` or with `Open Connection` or `Set Prompt` keyword. - -This is a convenience keyword that uses `Write` and `Read Until Prompt` -internally. Following two examples are thus functionally identical: - -| ${out} = | `Execute Command` | pwd | - -| `Write` | pwd | -| ${out} = | `Read Until Prompt` | - -See `Logging` section for more information about log levels and `Read -Until Prompt` for more information about the ``strip_prompt`` parameter. - - - - - -username -password -login_prompt=login: -password_prompt=Password: -login_timeout=1 second -login_incorrect=Login incorrect - -Logs in to the Telnet server with the given user information. - -This keyword reads from the connection until the ``login_prompt`` is -encountered and then types the given ``username``. Then it reads until -the ``password_prompt`` and types the given ``password``. In both cases -a newline is appended automatically and the connection specific -timeout used when waiting for outputs. - -How logging status is verified depends on whether a prompt is set for -this connection or not: - -1) If the prompt is set, this keyword reads the output until the prompt -is found using the normal timeout. If no prompt is found, login is -considered failed and also this keyword fails. Note that in this case -both ``login_timeout`` and ``login_incorrect`` arguments are ignored. - -2) If the prompt is not set, this keywords sleeps until ``login_timeout`` -and then reads all the output available on the connection. If the -output contains ``login_incorrect`` text, login is considered failed -and also this keyword fails. - -See `Configuration` section for more information about setting -newline, timeout, and prompt. - - - - - -host -alias=None -port=23 -timeout=None -newline=None -prompt=None -prompt_is_regexp=False -encoding=None -encoding_errors=None -default_log_level=None -window_size=None -environ_user=None -terminal_emulation=None -terminal_type=None -telnetlib_log_level=None -connection_timeout=None - -Opens a new Telnet connection to the given host and port. - -The ``timeout``, ``newline``, ``prompt``, ``prompt_is_regexp``, -``encoding``, ``default_log_level``, ``window_size``, ``environ_user``, -``terminal_emulation``, ``terminal_type`` and ``telnetlib_log_level`` -arguments get default values when the library is [#Importing|imported]. -Setting them here overrides those values for the opened connection. -See `Configuration`, `Terminal emulation` and `Logging` sections for -more information about these parameters and their possible values. - -Possible already opened connections are cached and it is possible to -switch back to them using `Switch Connection` keyword. It is possible to -switch either using explicitly given ``alias`` or using index returned -by this keyword. Indexing starts from 1 and is reset back to it by -`Close All Connections` keyword. - - - - - -loglevel=None - -Reads everything that is currently available in the output. - -Read output is both returned and logged. See `Logging` section for more -information about log levels. - - - - - -expected -loglevel=None - -Reads output until ``expected`` text is encountered. - -Text up to and including the match is returned and logged. If no match -is found, this keyword fails. How much to wait for the output depends -on the [#Configuration|configured timeout]. - -See `Logging` section for more information about log levels. Use -`Read Until Regexp` if more complex matching is needed. - - - - - -loglevel=None -strip_prompt=False - -Reads output until the prompt is encountered. - -This keyword requires the prompt to be [#Configuration|configured] -either in `importing` or with `Open Connection` or `Set Prompt` keyword. - -By default, text up to and including the prompt is returned and logged. -If no prompt is found, this keyword fails. How much to wait for the -output depends on the [#Configuration|configured timeout]. - -If you want to exclude the prompt from the returned output, set -``strip_prompt`` to a true value (see `Boolean arguments`). If your -prompt is a regular expression, make sure that the expression spans the -whole prompt, because only the part of the output that matches the -regular expression is stripped away. - -See `Logging` section for more information about log levels. - - - - - -*expected - -Reads output until any of the ``expected`` regular expressions match. - -This keyword accepts any number of regular expressions patterns or -compiled Python regular expression objects as arguments. Text up to -and including the first match to any of the regular expressions is -returned and logged. If no match is found, this keyword fails. How much -to wait for the output depends on the [#Configuration|configured timeout]. - -If the last given argument is a [#Logging|valid log level], it is used -as ``loglevel`` similarly as with `Read Until` keyword. - -See the documentation of -[http://docs.python.org/library/re.html|Python re module] -for more information about the supported regular expression syntax. -Notice that possible backslashes need to be escaped in Robot Framework -test data. - -Examples: -| `Read Until Regexp` | (#|$) | -| `Read Until Regexp` | first_regexp | second_regexp | -| `Read Until Regexp` | \\d{4}-\\d{2}-\\d{2} | DEBUG | - - - - - -level - -Sets the default log level used for `logging` in the current connection. - -The old default log level is returned and can be used to restore the -log level later. - -See `Configuration` section for more information about global and -connection specific configuration. - - - - - -encoding=None -errors=None - -Sets the encoding to use for `writing and reading` in the current connection. - -The given ``encoding`` specifies the encoding to use when written/read -text is encoded/decoded, and ``errors`` specifies the error handler to -use if encoding/decoding fails. Either of these can be omitted and in -that case the old value is not affected. Use string ``NONE`` to disable -encoding altogether. - -See `Configuration` section for more information about encoding and -error handlers, as well as global and connection specific configuration -in general. - -The old values are returned and can be used to restore the encoding -and the error handler later. See `Set Prompt` for a similar example. - -If terminal emulation is used, the encoding can not be changed on an open -connection. - - - - - -newline - -Sets the newline used by `Write` keyword in the current connection. - -The old newline is returned and can be used to restore the newline later. -See `Set Timeout` for a similar example. - -If terminal emulation is used, the newline can not be changed on an open -connection. - -See `Configuration` section for more information about global and -connection specific configuration. - - - - - -prompt -prompt_is_regexp=False - -Sets the prompt used by `Read Until Prompt` and `Login` in the current connection. - -If ``prompt_is_regexp`` is given a true value (see `Boolean arguments`), -the given ``prompt`` is considered to be a regular expression. - -The old prompt is returned and can be used to restore the prompt later. - -Example: -| ${prompt} | ${regexp} = | `Set Prompt` | $ | -| `Do Something` | -| `Set Prompt` | ${prompt} | ${regexp} | - -See the documentation of -[http://docs.python.org/library/re.html|Python re module] -for more information about the supported regular expression syntax. -Notice that possible backslashes need to be escaped in Robot Framework -test data. - -See `Configuration` section for more information about global and -connection specific configuration. - - - - - -level - -Sets the log level used for `logging` in the underlying ``telnetlib``. - -Note that ``telnetlib`` can be very noisy thus using the level ``NONE`` -can shutdown the messages generated by this library. - - - - - -timeout - -Sets the timeout used for waiting output in the current connection. - -Read operations that expect some output to appear (`Read Until`, `Read -Until Regexp`, `Read Until Prompt`, `Login`) use this timeout and fail -if the expected output does not appear before this timeout expires. - -The ``timeout`` must be given in `time string format`. The old timeout -is returned and can be used to restore the timeout later. - -Example: -| ${old} = | `Set Timeout` | 2 minute 30 seconds | -| `Do Something` | -| `Set Timeout` | ${old} | - -See `Configuration` section for more information about global and -connection specific configuration. - - - - - -index_or_alias - -Switches between active connections using an index or an alias. - -Aliases can be given to `Open Connection` keyword which also always -returns the connection index. - -This keyword returns the index of previous active connection. - -Example: -| `Open Connection` | myhost.net | | | -| `Login` | john | secret | | -| `Write` | some command | | | -| `Open Connection` | yourhost.com | 2nd conn | | -| `Login` | root | password | | -| `Write` | another cmd | | | -| ${old index}= | `Switch Connection` | 1 | # index | -| `Write` | something | | | -| `Switch Connection` | 2nd conn | | # alias | -| `Write` | whatever | | | -| `Switch Connection` | ${old index} | | # back to original | -| [Teardown] | `Close All Connections` | | | - -The example above expects that there were no other open -connections when opening the first one, because it used index -``1`` when switching to the connection later. If you are not -sure about that, you can store the index into a variable as -shown below. - -| ${index} = | `Open Connection` | myhost.net | -| `Do Something` | | | -| `Switch Connection` | ${index} | | - - - - - -text -loglevel=None - -Writes the given text plus a newline into the connection. - -The newline character sequence to use can be [#Configuration|configured] -both globally and per connection basis. The default value is ``CRLF``. - -This keyword consumes the written text, until the added newline, from -the output and logs and returns it. The given text itself must not -contain newlines. Use `Write Bare` instead if either of these features -causes a problem. - -*Note:* This keyword does not return the possible output of the executed -command. To get the output, one of the `Read ...` `keywords` must be -used. See `Writing and reading` section for more details. - -See `Logging` section for more information about log levels. - - - - - -text - -Writes the given text, and nothing else, into the connection. - -This keyword does not append a newline nor consume the written text. -Use `Write` if these features are needed. - - - - - -character - -Writes the given control character into the connection. - -The control character is prepended with an IAC (interpret as command) -character. - -The following control character names are supported: BRK, IP, AO, AYT, -EC, EL, NOP. Additionally, you can use arbitrary numbers to send any -control character. - -Example: -| Write Control Character | BRK | # Send Break command | -| Write Control Character | 241 | # Send No operation command | - - - - - -text -expected -timeout -retry_interval -loglevel=None - -Writes the given ``text`` repeatedly, until ``expected`` appears in the output. - -``text`` is written without appending a newline and it is consumed from -the output before trying to find ``expected``. If ``expected`` does not -appear in the output within ``timeout``, this keyword fails. - -``retry_interval`` defines the time to wait ``expected`` to appear before -writing the ``text`` again. Consuming the written ``text`` is subject to -the normal [#Configuration|configured timeout]. - -Both ``timeout`` and ``retry_interval`` must be given in `time string -format`. See `Logging` section for more information about log levels. - -Example: -| Write Until Expected Output | ps -ef| grep myprocess\r\n | myprocess | -| ... | 5 s | 0.5 s | - -The above example writes command ``ps -ef | grep myprocess\r\n`` until -``myprocess`` appears in the output. The command is written every 0.5 -seconds and the keyword fails if ``myprocess`` does not appear in -the output in 5 seconds. - - - - diff --git a/libspecs/XML.libspec b/libspecs/XML.libspec deleted file mode 100644 index 0ac73f9..0000000 --- a/libspecs/XML.libspec +++ /dev/null @@ -1,1365 +0,0 @@ - - -3.1.2 -global -yes -Robot Framework test library for verifying and modifying XML documents. - -As the name implies, _XML_ is a test library for verifying contents of XML -files. In practice it is a pretty thin wrapper on top of Python's -[http://docs.python.org/library/xml.etree.elementtree.html|ElementTree XML API]. - -The library has the following main usages: - -- Parsing an XML file, or a string containing XML, into an XML element - structure and finding certain elements from it for for further analysis - (e.g. `Parse XML` and `Get Element` keywords). -- Getting text or attributes of elements - (e.g. `Get Element Text` and `Get Element Attribute`). -- Directly verifying text, attributes, or whole elements - (e.g `Element Text Should Be` and `Elements Should Be Equal`). -- Modifying XML and saving it (e.g. `Set Element Text`, `Add Element` - and `Save XML`). - -== Table of contents == - -- `Parsing XML` -- `Using lxml` -- `Example` -- `Finding elements with xpath` -- `Element attributes` -- `Handling XML namespaces` -- `Boolean arguments` -- `Pattern matching` -- `Shortcuts` -- `Keywords` - -= Parsing XML = - -XML can be parsed into an element structure using `Parse XML` keyword. -It accepts both paths to XML files and strings that contain XML. The -keyword returns the root element of the structure, which then contains -other elements as its children and their children. Possible comments and -processing instructions in the source XML are removed. - -XML is not validated during parsing even if has a schema defined. How -possible doctype elements are handled otherwise depends on the used XML -module and on the platform. The standard ElementTree strips doctypes -altogether but when `using lxml` they are preserved when XML is saved. - -The element structure returned by `Parse XML`, as well as elements -returned by keywords such as `Get Element`, can be used as the ``source`` -argument with other keywords. In addition to an already parsed XML -structure, other keywords also accept paths to XML files and strings -containing XML similarly as `Parse XML`. Notice that keywords that modify -XML do not write those changes back to disk even if the source would be -given as a path to a file. Changes must always saved explicitly using -`Save XML` keyword. - -When the source is given as a path to a file, the forward slash character -(``/``) can be used as the path separator regardless the operating system. -On Windows also the backslash works, but it the test data it needs to be -escaped by doubling it (``\\``). Using the built-in variable ``${/}`` -naturally works too. - -= Using lxml = - -By default this library uses Python's standard -[http://docs.python.org/library/xml.etree.elementtree.html|ElementTree] -module for parsing XML, but it can be configured to use -[http://lxml.de|lxml] module instead when `importing` the library. -The resulting element structure has same API regardless which module -is used for parsing. - -The main benefits of using lxml is that it supports richer xpath syntax -than the standard ElementTree and enables using `Evaluate Xpath` keyword. -It also preserves the doctype and possible namespace prefixes saving XML. - -= Example = - -The following simple example demonstrates parsing XML and verifying its -contents both using keywords in this library and in _BuiltIn_ and -_Collections_ libraries. How to use xpath expressions to find elements -and what attributes the returned elements contain are discussed, with -more examples, in `Finding elements with xpath` and `Element attributes` -sections. - -In this example, as well as in many other examples in this documentation, -``${XML}`` refers to the following example XML document. In practice -``${XML}`` could either be a path to an XML file or it could contain the XML -itself. - -| <example> -| <first id="1">text</first> -| <second id="2"> -| <child/> -| </second> -| <third> -| <child>more text</child> -| <second id="child"/> -| <child><grandchild/></child> -| </third> -| <html> -| <p> -| Text with <b>bold</b> and <i>italics</i>. -| </p> -| </html> -| </example> - -| ${root} = | `Parse XML` | ${XML} | | | -| `Should Be Equal` | ${root.tag} | example | | | -| ${first} = | `Get Element` | ${root} | first | | -| `Should Be Equal` | ${first.text} | text | | | -| `Dictionary Should Contain Key` | ${first.attrib} | id | | -| `Element Text Should Be` | ${first} | text | | | -| `Element Attribute Should Be` | ${first} | id | 1 | | -| `Element Attribute Should Be` | ${root} | id | 1 | xpath=first | -| `Element Attribute Should Be` | ${XML} | id | 1 | xpath=first | - -Notice that in the example three last lines are equivalent. Which one to -use in practice depends on which other elements you need to get or verify. -If you only need to do one verification, using the last line alone would -suffice. If more verifications are needed, parsing the XML with `Parse XML` -only once would be more efficient. - -= Finding elements with xpath = - -ElementTree, and thus also this library, supports finding elements using -xpath expressions. ElementTree does not, however, support the full xpath -standard. The supported xpath syntax is explained below and -[https://docs.python.org/library/xml.etree.elementtree.html#xpath-support| -ElementTree documentation] provides more details. In the examples -``${XML}`` refers to the same XML structure as in the earlier example. - -If lxml support is enabled when `importing` the library, the whole -[http://www.w3.org/TR/xpath/|xpath 1.0 standard] is supported. -That includes everything listed below but also lot of other useful -constructs. - -== Tag names == - -When just a single tag name is used, xpath matches all direct child -elements that have that tag name. - -| ${elem} = | `Get Element` | ${XML} | third | -| `Should Be Equal` | ${elem.tag} | third | | -| @{children} = | `Get Elements` | ${elem} | child | -| `Length Should Be` | ${children} | 2 | | - -== Paths == - -Paths are created by combining tag names with a forward slash (``/``). For -example, ``parent/child`` matches all ``child`` elements under ``parent`` -element. Notice that if there are multiple ``parent`` elements that all -have ``child`` elements, ``parent/child`` xpath will match all these -``child`` elements. - -| ${elem} = | `Get Element` | ${XML} | second/child | -| `Should Be Equal` | ${elem.tag} | child | | -| ${elem} = | `Get Element` | ${XML} | third/child/grandchild | -| `Should Be Equal` | ${elem.tag} | grandchild | | - -== Wildcards == - -An asterisk (``*``) can be used in paths instead of a tag name to denote -any element. - -| @{children} = | `Get Elements` | ${XML} | */child | -| `Length Should Be` | ${children} | 3 | | - -== Current element == - -The current element is denoted with a dot (``.``). Normally the current -element is implicit and does not need to be included in the xpath. - -== Parent element == - -The parent element of another element is denoted with two dots (``..``). -Notice that it is not possible to refer to the parent of the current -element. - -| ${elem} = | `Get Element` | ${XML} | */second/.. | -| `Should Be Equal` | ${elem.tag} | third | | - -== Search all sub elements == - -Two forward slashes (``//``) mean that all sub elements, not only the -direct children, are searched. If the search is started from the current -element, an explicit dot is required. - -| @{elements} = | `Get Elements` | ${XML} | .//second | -| `Length Should Be` | ${elements} | 2 | | -| ${b} = | `Get Element` | ${XML} | html//b | -| `Should Be Equal` | ${b.text} | bold | | - -== Predicates == - -Predicates allow selecting elements using also other criteria than tag -names, for example, attributes or position. They are specified after the -normal tag name or path using syntax ``path[predicate]``. The path can have -wildcards and other special syntax explained earlier. What predicates -the standard ElementTree supports is explained in the table below. - -| = Predicate = | = Matches = | = Example = | -| @attrib | Elements with attribute ``attrib``. | second[@id] | -| @attrib="value" | Elements with attribute ``attrib`` having value ``value``. | *[@id="2"] | -| position | Elements at the specified position. Position can be an integer (starting from 1), expression ``last()``, or relative expression like ``last() - 1``. | third/child[1] | -| tag | Elements with a child element named ``tag``. | third/child[grandchild] | - -Predicates can also be stacked like ``path[predicate1][predicate2]``. -A limitation is that possible position predicate must always be first. - -= Element attributes = - -All keywords returning elements, such as `Parse XML`, and `Get Element`, -return ElementTree's -[http://docs.python.org/library/xml.etree.elementtree.html#element-objects|Element objects]. -These elements can be used as inputs for other keywords, but they also -contain several useful attributes that can be accessed directly using -the extended variable syntax. - -The attributes that are both useful and convenient to use in the test -data are explained below. Also other attributes, including methods, can -be accessed, but that is typically better to do in custom libraries than -directly in the test data. - -The examples use the same ``${XML}`` structure as the earlier examples. - -== tag == - -The tag of the element. - -| ${root} = | `Parse XML` | ${XML} | -| `Should Be Equal` | ${root.tag} | example | - -== text == - -The text that the element contains or Python ``None`` if the element has no -text. Notice that the text _does not_ contain texts of possible child -elements nor text after or between children. Notice also that in XML -whitespace is significant, so the text contains also possible indentation -and newlines. To get also text of the possible children, optionally -whitespace normalized, use `Get Element Text` keyword. - -| ${1st} = | `Get Element` | ${XML} | first | -| `Should Be Equal` | ${1st.text} | text | | -| ${2nd} = | `Get Element` | ${XML} | second/child | -| `Should Be Equal` | ${2nd.text} | ${NONE} | | -| ${p} = | `Get Element` | ${XML} | html/p | -| `Should Be Equal` | ${p.text} | \n${SPACE*6}Text with${SPACE} | - -== tail == - -The text after the element before the next opening or closing tag. Python -``None`` if the element has no tail. Similarly as with ``text``, also -``tail`` contains possible indentation and newlines. - -| ${b} = | `Get Element` | ${XML} | html/p/b | -| `Should Be Equal` | ${b.tail} | ${SPACE}and${SPACE} | - -== attrib == - -A Python dictionary containing attributes of the element. - -| ${2nd} = | `Get Element` | ${XML} | second | -| `Should Be Equal` | ${2nd.attrib['id']} | 2 | | -| ${3rd} = | `Get Element` | ${XML} | third | -| `Should Be Empty` | ${3rd.attrib} | | | - -= Handling XML namespaces = - -ElementTree and lxml handle possible namespaces in XML documents by adding -the namespace URI to tag names in so called Clark Notation. That is -inconvenient especially with xpaths, and by default this library strips -those namespaces away and moves them to ``xmlns`` attribute instead. That -can be avoided by passing ``keep_clark_notation`` argument to `Parse XML` -keyword. Alternatively `Parse XML` supports stripping namespace information -altogether by using ``strip_namespaces`` argument. The pros and cons of -different approaches are discussed in more detail below. - -== How ElementTree handles namespaces == - -If an XML document has namespaces, ElementTree adds namespace information -to tag names in [http://www.jclark.com/xml/xmlns.htm|Clark Notation] -(e.g. ``{http://ns.uri}tag``) and removes original ``xmlns`` attributes. -This is done both with default namespaces and with namespaces with a prefix. -How it works in practice is illustrated by the following example, where -``${NS}`` variable contains this XML document: - -| <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" -| xmlns="http://www.w3.org/1999/xhtml"> -| <xsl:template match="/"> -| <html></html> -| </xsl:template> -| </xsl:stylesheet> - -| ${root} = | `Parse XML` | ${NS} | keep_clark_notation=yes | -| `Should Be Equal` | ${root.tag} | {http://www.w3.org/1999/XSL/Transform}stylesheet | -| `Element Should Exist` | ${root} | {http://www.w3.org/1999/XSL/Transform}template/{http://www.w3.org/1999/xhtml}html | -| `Should Be Empty` | ${root.attrib} | - -As you can see, including the namespace URI in tag names makes xpaths -really long and complex. - -If you save the XML, ElementTree moves namespace information back to -``xmlns`` attributes. Unfortunately it does not restore the original -prefixes: - -| <ns0:stylesheet xmlns:ns0="http://www.w3.org/1999/XSL/Transform"> -| <ns0:template match="/"> -| <ns1:html xmlns:ns1="http://www.w3.org/1999/xhtml"></ns1:html> -| </ns0:template> -| </ns0:stylesheet> - -The resulting output is semantically same as the original, but mangling -prefixes like this may still not be desirable. Notice also that the actual -output depends slightly on ElementTree version. - -== Default namespace handling == - -Because the way ElementTree handles namespaces makes xpaths so complicated, -this library, by default, strips namespaces from tag names and moves that -information back to ``xmlns`` attributes. How this works in practice is -shown by the example below, where ``${NS}`` variable contains the same XML -document as in the previous example. - -| ${root} = | `Parse XML` | ${NS} | -| `Should Be Equal` | ${root.tag} | stylesheet | -| `Element Should Exist` | ${root} | template/html | -| `Element Attribute Should Be` | ${root} | xmlns | http://www.w3.org/1999/XSL/Transform | -| `Element Attribute Should Be` | ${root} | xmlns | http://www.w3.org/1999/xhtml | xpath=template/html | - -Now that tags do not contain namespace information, xpaths are simple again. - -A minor limitation of this approach is that namespace prefixes are lost. -As a result the saved output is not exactly same as the original one in -this case either: - -| <stylesheet xmlns="http://www.w3.org/1999/XSL/Transform"> -| <template match="/"> -| <html xmlns="http://www.w3.org/1999/xhtml"></html> -| </template> -| </stylesheet> - -Also this output is semantically same as the original. If the original XML -had only default namespaces, the output would also look identical. - -== Namespaces when using lxml == - -This library handles namespaces same way both when `using lxml` and when -not using it. There are, however, differences how lxml internally handles -namespaces compared to the standard ElementTree. The main difference is -that lxml stores information about namespace prefixes and they are thus -preserved if XML is saved. Another visible difference is that lxml includes -namespace information in child elements got with `Get Element` if the -parent element has namespaces. - -== Stripping namespaces altogether == - -Because namespaces often add unnecessary complexity, `Parse XML` supports -stripping them altogether by using ``strip_namespaces=True``. When this -option is enabled, namespaces are not shown anywhere nor are they included -if XML is saved. - -== Attribute namespaces == - -Attributes in XML documents are, by default, in the same namespaces as -the element they belong to. It is possible to use different namespaces -by using prefixes, but this is pretty rare. - -If an attribute has a namespace prefix, ElementTree will replace it with -Clark Notation the same way it handles elements. Because stripping -namespaces from attributes could cause attribute conflicts, this library -does not handle attribute namespaces at all. Thus the following example -works the same way regardless how namespaces are handled. - -| ${root} = | `Parse XML` | <root id="1" ns:id="2" xmlns:ns="http://my.ns"/> | -| `Element Attribute Should Be` | ${root} | id | 1 | -| `Element Attribute Should Be` | ${root} | {http://my.ns}id | 2 | - -= Boolean arguments = - -Some keywords accept arguments that are handled as Boolean values true or -false. If such an argument is given as a string, it is considered false if -it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or -``0``, case-insensitively. Other strings are considered true regardless -their value, and other argument types are tested using the same -[http://docs.python.org/library/stdtypes.html#truth|rules as in Python]. - -True examples: -| `Parse XML` | ${XML} | keep_clark_notation=True | # Strings are generally true. | -| `Parse XML` | ${XML} | keep_clark_notation=yes | # Same as the above. | -| `Parse XML` | ${XML} | keep_clark_notation=${TRUE} | # Python ``True`` is true. | -| `Parse XML` | ${XML} | keep_clark_notation=${42} | # Numbers other than 0 are true. | - -False examples: -| `Parse XML` | ${XML} | keep_clark_notation=False | # String ``false`` is false. | -| `Parse XML` | ${XML} | keep_clark_notation=no | # Also string ``no`` is false. | -| `Parse XML` | ${XML} | keep_clark_notation=${EMPTY} | # Empty string is false. | -| `Parse XML` | ${XML} | keep_clark_notation=${FALSE} | # Python ``False`` is false. | - -Considering string ``NONE`` false is new in Robot Framework 3.0.3 and -considering also ``OFF`` and ``0`` false is new in Robot Framework 3.1. - -== Pattern matching == - -Some keywords, for example `Elements Should Match`, support so called -[http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where: - -| ``*`` | matches any string, even an empty string | -| ``?`` | matches any single character | -| ``[chars]`` | matches one character in the bracket | -| ``[!chars]`` | matches one character not in the bracket | -| ``[a-z]`` | matches one character from the range in the bracket | -| ``[!a-z]`` | matches one character not from the range in the bracket | - -Unlike with glob patterns normally, path separator characters ``/`` and -``\`` and the newline character ``\n`` are matches by the above -wildcards. - -Support for brackets like ``[abc]`` and ``[!a-z]`` is new in -Robot Framework 3.1 - - -use_lxml=False - -Import library with optionally lxml mode enabled. - -By default this library uses Python's standard -[http://docs.python.org/library/xml.etree.elementtree.html|ElementTree] -module for parsing XML. If ``use_lxml`` argument is given a true value -(see `Boolean arguments`), the library will use [http://lxml.de|lxml] -module instead. See `Using lxml` section for benefits provided by lxml. - -Using lxml requires that the lxml module is installed on the system. -If lxml mode is enabled but the module is not installed, this library -will emit a warning and revert back to using the standard ElementTree. - - - - - -source -element -index=None -xpath=. - -Adds a child element to the specified element. - -The element to whom to add the new element is specified using ``source`` -and ``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -The ``element`` to add can be specified as a path to an XML file or -as a string containing XML, or it can be an already parsed XML element. -The element is copied before adding so modifying either the original -or the added element has no effect on the other -. -The element is added as the last child by default, but a custom index -can be used to alter the position. Indices start from zero (0 = first -position, 1 = second position, etc.), and negative numbers refer to -positions at the end (-1 = second last position, -2 = third last, etc.). - -Examples using ``${XML}`` structure from `Example`: -| Add Element | ${XML} | <new id="x"><c1/></new> | -| Add Element | ${XML} | <c2/> | xpath=new | -| Add Element | ${XML} | <c3/> | index=1 | xpath=new | -| ${new} = | Get Element | ${XML} | new | -| Elements Should Be Equal | ${new} | <new id="x"><c1/><c3/><c2/></new> | - -Use `Remove Element` or `Remove Elements` to remove elements. - - - - - -source -xpath=. -clear_tail=False - -Clears the contents of the specified element. - -The element to clear is specified using ``source`` and ``xpath``. They -have exactly the same semantics as with `Get Element` keyword. -The resulting XML structure is returned, and if the ``source`` is -an already parsed XML structure, it is also modified in place. - -Clearing the element means removing its text, attributes, and children. -Element's tail text is not removed by default, but that can be changed -by giving ``clear_tail`` a true value (see `Boolean arguments`). See -`Element attributes` section for more information about tail in -general. - -Examples using ``${XML}`` structure from `Example`: -| Clear Element | ${XML} | xpath=first | -| ${first} = | Get Element | ${XML} | xpath=first | -| Elements Should Be Equal | ${first} | <first/> | -| Clear Element | ${XML} | xpath=html/p/b | clear_tail=yes | -| Element Text Should Be | ${XML} | Text with italics. | xpath=html/p | normalize_whitespace=yes | -| Clear Element | ${XML} | -| Elements Should Be Equal | ${XML} | <example/> | - -Use `Remove Element` to remove the whole element. - - - - - -source -xpath=. - -Returns a copy of the specified element. - -The element to copy is specified using ``source`` and ``xpath``. They -have exactly the same semantics as with `Get Element` keyword. - -If the copy or the original element is modified afterwards, the changes -have no effect on the other. - -Examples using ``${XML}`` structure from `Example`: -| ${elem} = | Get Element | ${XML} | xpath=first | -| ${copy1} = | Copy Element | ${elem} | -| ${copy2} = | Copy Element | ${XML} | xpath=first | -| Set Element Text | ${XML} | new text | xpath=first | -| Set Element Attribute | ${copy1} | id | new | -| Elements Should Be Equal | ${elem} | <first id="1">new text</first> | -| Elements Should Be Equal | ${copy1} | <first id="new">text</first> | -| Elements Should Be Equal | ${copy2} | <first id="1">text</first> | - - - - - -source -name -expected -xpath=. -message=None - -Verifies that the specified attribute is ``expected``. - -The element whose attribute is verified is specified using ``source`` -and ``xpath``. They have exactly the same semantics as with -`Get Element` keyword. - -The keyword passes if the attribute ``name`` of the element is equal to -the ``expected`` value, and otherwise it fails. The default error -message can be overridden with the ``message`` argument. - -To test that the element does not have a certain attribute, Python -``None`` (i.e. variable ``${NONE}``) can be used as the expected value. -A cleaner alternative is using `Element Should Not Have Attribute`. - -Examples using ``${XML}`` structure from `Example`: -| Element Attribute Should Be | ${XML} | id | 1 | xpath=first | -| Element Attribute Should Be | ${XML} | id | ${NONE} | | - -See also `Element Attribute Should Match` and `Get Element Attribute`. - - - - - -source -name -pattern -xpath=. -message=None - -Verifies that the specified attribute matches ``expected``. - -This keyword works exactly like `Element Attribute Should Be` except -that the expected value can be given as a pattern that the attribute of -the element must match. - -Pattern matching is similar as matching files in a shell with -``*``, ``?`` and ``[chars]`` acting as wildcards. See the -`Pattern matching` section for more information. - -Examples using ``${XML}`` structure from `Example`: -| Element Attribute Should Match | ${XML} | id | ? | xpath=first | -| Element Attribute Should Match | ${XML} | id | c*d | xpath=third/second | - - - - - -source -xpath=. -message=None - -Verifies that one or more element match the given ``xpath``. - -Arguments ``source`` and ``xpath`` have exactly the same semantics as -with `Get Elements` keyword. Keyword passes if the ``xpath`` matches -one or more elements in the ``source``. The default error message can -be overridden with the ``message`` argument. - -See also `Element Should Not Exist` as well as `Get Element Count` -that this keyword uses internally. - - - - - -source -xpath=. -message=None - -Verifies that no element match the given ``xpath``. - -Arguments ``source`` and ``xpath`` have exactly the same semantics as -with `Get Elements` keyword. Keyword fails if the ``xpath`` matches any -element in the ``source``. The default error message can be overridden -with the ``message`` argument. - -See also `Element Should Exist` as well as `Get Element Count` -that this keyword uses internally. - - - - - -source -name -xpath=. -message=None - -Verifies that the specified element does not have attribute ``name``. - -The element whose attribute is verified is specified using ``source`` -and ``xpath``. They have exactly the same semantics as with -`Get Element` keyword. - -The keyword fails if the specified element has attribute ``name``. The -default error message can be overridden with the ``message`` argument. - -Examples using ``${XML}`` structure from `Example`: -| Element Should Not Have Attribute | ${XML} | id | -| Element Should Not Have Attribute | ${XML} | xxx | xpath=first | - -See also `Get Element Attribute`, `Get Element Attributes`, -`Element Text Should Be` and `Element Text Should Match`. - - - - - -source -expected -xpath=. -normalize_whitespace=False -message=None - -Verifies that the text of the specified element is ``expected``. - -The element whose text is verified is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -The text to verify is got from the specified element using the same -logic as with `Get Element Text`. This includes optional whitespace -normalization using the ``normalize_whitespace`` option. - -The keyword passes if the text of the element is equal to the -``expected`` value, and otherwise it fails. The default error message -can be overridden with the ``message`` argument. Use `Element Text -Should Match` to verify the text against a pattern instead of an exact -value. - -Examples using ``${XML}`` structure from `Example`: -| Element Text Should Be | ${XML} | text | xpath=first | -| Element Text Should Be | ${XML} | ${EMPTY} | xpath=second/child | -| ${paragraph} = | Get Element | ${XML} | xpath=html/p | -| Element Text Should Be | ${paragraph} | Text with bold and italics. | normalize_whitespace=yes | - - - - - -source -pattern -xpath=. -normalize_whitespace=False -message=None - -Verifies that the text of the specified element matches ``expected``. - -This keyword works exactly like `Element Text Should Be` except that -the expected value can be given as a pattern that the text of the -element must match. - -Pattern matching is similar as matching files in a shell with -``*``, ``?`` and ``[chars]`` acting as wildcards. See the -`Pattern matching` section for more information. - -Examples using ``${XML}`` structure from `Example`: -| Element Text Should Match | ${XML} | t??? | xpath=first | -| ${paragraph} = | Get Element | ${XML} | xpath=html/p | -| Element Text Should Match | ${paragraph} | Text with * and *. | normalize_whitespace=yes | - - - - - -source -xpath=. -encoding=None - -Returns the string representation of the specified element. - -The element to convert to a string is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -By default the string is returned as Unicode. If ``encoding`` argument -is given any value, the string is returned as bytes in the specified -encoding. The resulting string never contains the XML declaration. - -See also `Log Element` and `Save XML`. - - - - - -source -expected -exclude_children=False -normalize_whitespace=False - -Verifies that the given ``source`` element is equal to ``expected``. - -Both ``source`` and ``expected`` can be given as a path to an XML file, -as a string containing XML, or as an already parsed XML element -structure. See `introduction` for more information about parsing XML in -general. - -The keyword passes if the ``source`` element and ``expected`` element -are equal. This includes testing the tag names, texts, and attributes -of the elements. By default also child elements are verified the same -way, but this can be disabled by setting ``exclude_children`` to a -true value (see `Boolean arguments`). - -All texts inside the given elements are verified, but possible text -outside them is not. By default texts must match exactly, but setting -``normalize_whitespace`` to a true value makes text verification -independent on newlines, tabs, and the amount of spaces. For more -details about handling text see `Get Element Text` keyword and -discussion about elements' `text` and `tail` attributes in the -`introduction`. - -Examples using ``${XML}`` structure from `Example`: -| ${first} = | Get Element | ${XML} | first | -| Elements Should Be Equal | ${first} | <first id="1">text</first> | -| ${p} = | Get Element | ${XML} | html/p | -| Elements Should Be Equal | ${p} | <p>Text with <b>bold</b> and <i>italics</i>.</p> | normalize_whitespace=yes | -| Elements Should Be Equal | ${p} | <p>Text with</p> | exclude | normalize | - -The last example may look a bit strange because the ``<p>`` element -only has text ``Text with``. The reason is that rest of the text -inside ``<p>`` actually belongs to the child elements. This includes -the ``.`` at the end that is the `tail` text of the ``<i>`` element. - -See also `Elements Should Match`. - - - - - -source -expected -exclude_children=False -normalize_whitespace=False - -Verifies that the given ``source`` element matches ``expected``. - -This keyword works exactly like `Elements Should Be Equal` except that -texts and attribute values in the expected value can be given as -patterns. - -Pattern matching is similar as matching files in a shell with -``*``, ``?`` and ``[chars]`` acting as wildcards. See the -`Pattern matching` section for more information. - -Examples using ``${XML}`` structure from `Example`: -| ${first} = | Get Element | ${XML} | first | -| Elements Should Match | ${first} | <first id="?">*</first> | - -See `Elements Should Be Equal` for more examples. - - - - - -source -expression -context=. - -Evaluates the given xpath expression and returns results. - -The element in which context the expression is executed is specified -using ``source`` and ``context`` arguments. They have exactly the same -semantics as ``source`` and ``xpath`` arguments have with `Get Element` -keyword. - -The xpath expression to evaluate is given as ``expression`` argument. -The result of the evaluation is returned as-is. - -Examples using ``${XML}`` structure from `Example`: -| ${count} = | Evaluate Xpath | ${XML} | count(third/*) | -| Should Be Equal | ${count} | ${3} | -| ${text} = | Evaluate Xpath | ${XML} | string(descendant::second[last()]/@id) | -| Should Be Equal | ${text} | child | -| ${bold} = | Evaluate Xpath | ${XML} | boolean(preceding-sibling::*[1] = 'bold') | context=html/p/i | -| Should Be Equal | ${bold} | ${True} | - -This keyword works only if lxml mode is taken into use when `importing` -the library. - - - - - -source -xpath=. - -Returns the child elements of the specified element as a list. - -The element whose children to return is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -All the direct child elements of the specified element are returned. -If the element has no children, an empty list is returned. - -Examples using ``${XML}`` structure from `Example`: -| ${children} = | Get Child Elements | ${XML} | | -| Length Should Be | ${children} | 4 | | -| ${children} = | Get Child Elements | ${XML} | xpath=first | -| Should Be Empty | ${children} | | | - - - - - -source -xpath=. - -Returns an element in the ``source`` matching the ``xpath``. - -The ``source`` can be a path to an XML file, a string containing XML, or -an already parsed XML element. The ``xpath`` specifies which element to -find. See the `introduction` for more details about both the possible -sources and the supported xpath syntax. - -The keyword fails if more, or less, than one element matches the -``xpath``. Use `Get Elements` if you want all matching elements to be -returned. - -Examples using ``${XML}`` structure from `Example`: -| ${element} = | Get Element | ${XML} | second | -| ${child} = | Get Element | ${element} | child | - -`Parse XML` is recommended for parsing XML when the whole structure -is needed. It must be used if there is a need to configure how XML -namespaces are handled. - -Many other keywords use this keyword internally, and keywords modifying -XML are typically documented to both to modify the given source and -to return it. Modifying the source does not apply if the source is -given as a string. The XML structure parsed based on the string and -then modified is nevertheless returned. - - - - - -source -name -xpath=. -default=None - -Returns the named attribute of the specified element. - -The element whose attribute to return is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -The value of the attribute ``name`` of the specified element is returned. -If the element does not have such element, the ``default`` value is -returned instead. - -Examples using ``${XML}`` structure from `Example`: -| ${attribute} = | Get Element Attribute | ${XML} | id | xpath=first | -| Should Be Equal | ${attribute} | 1 | | | -| ${attribute} = | Get Element Attribute | ${XML} | xx | xpath=first | default=value | -| Should Be Equal | ${attribute} | value | | | - -See also `Get Element Attributes`, `Element Attribute Should Be`, -`Element Attribute Should Match` and `Element Should Not Have Attribute`. - - - - - -source -xpath=. - -Returns all attributes of the specified element. - -The element whose attributes to return is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -Attributes are returned as a Python dictionary. It is a copy of the -original attributes so modifying it has no effect on the XML structure. - -Examples using ``${XML}`` structure from `Example`: -| ${attributes} = | Get Element Attributes | ${XML} | first | -| Dictionary Should Contain Key | ${attributes} | id | | -| ${attributes} = | Get Element Attributes | ${XML} | third | -| Should Be Empty | ${attributes} | | | - -Use `Get Element Attribute` to get the value of a single attribute. - - - - - -source -xpath=. - -Returns and logs how many elements the given ``xpath`` matches. - -Arguments ``source`` and ``xpath`` have exactly the same semantics as -with `Get Elements` keyword that this keyword uses internally. - -See also `Element Should Exist` and `Element Should Not Exist`. - - - - - -source -xpath=. -normalize_whitespace=False - -Returns all text of the element, possibly whitespace normalized. - -The element whose text to return is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. - -This keyword returns all the text of the specified element, including -all the text its children and grandchildren contain. If the element -has no text, an empty string is returned. The returned text is thus not -always the same as the `text` attribute of the element. - -By default all whitespace, including newlines and indentation, inside -the element is returned as-is. If ``normalize_whitespace`` is given -a true value (see `Boolean arguments`), then leading and trailing -whitespace is stripped, newlines and tabs converted to spaces, and -multiple spaces collapsed into one. This is especially useful when -dealing with HTML data. - -Examples using ``${XML}`` structure from `Example`: -| ${text} = | Get Element Text | ${XML} | first | -| Should Be Equal | ${text} | text | | -| ${text} = | Get Element Text | ${XML} | second/child | -| Should Be Empty | ${text} | | | -| ${paragraph} = | Get Element | ${XML} | html/p | -| ${text} = | Get Element Text | ${paragraph} | normalize_whitespace=yes | -| Should Be Equal | ${text} | Text with bold and italics. | - -See also `Get Elements Texts`, `Element Text Should Be` and -`Element Text Should Match`. - - - - - -source -xpath - -Returns a list of elements in the ``source`` matching the ``xpath``. - -The ``source`` can be a path to an XML file, a string containing XML, or -an already parsed XML element. The ``xpath`` specifies which element to -find. See the `introduction` for more details. - -Elements matching the ``xpath`` are returned as a list. If no elements -match, an empty list is returned. Use `Get Element` if you want to get -exactly one match. - -Examples using ``${XML}`` structure from `Example`: -| ${children} = | Get Elements | ${XML} | third/child | -| Length Should Be | ${children} | 2 | | -| ${children} = | Get Elements | ${XML} | first/child | -| Should Be Empty | ${children} | | | - - - - - -source -xpath -normalize_whitespace=False - -Returns text of all elements matching ``xpath`` as a list. - -The elements whose text to return is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Elements` -keyword. - -The text of the matched elements is returned using the same logic -as with `Get Element Text`. This includes optional whitespace -normalization using the ``normalize_whitespace`` option. - -Examples using ``${XML}`` structure from `Example`: -| @{texts} = | Get Elements Texts | ${XML} | third/child | -| Length Should Be | ${texts} | 2 | | -| Should Be Equal | @{texts}[0] | more text | | -| Should Be Equal | @{texts}[1] | ${EMPTY} | | - - - - - -source -level=INFO -xpath=. - -Logs the string representation of the specified element. - -The element specified with ``source`` and ``xpath`` is first converted -into a string using `Element To String` keyword internally. The -resulting string is then logged using the given ``level``. - -The logged string is also returned. - - - - - -source -keep_clark_notation=False -strip_namespaces=False - -Parses the given XML file or string into an element structure. - -The ``source`` can either be a path to an XML file or a string -containing XML. In both cases the XML is parsed into ElementTree -[http://docs.python.org/library/xml.etree.elementtree.html#element-objects|element structure] -and the root element is returned. Possible comments and processing -instructions in the source XML are removed. - -As discussed in `Handling XML namespaces` section, this keyword, by -default, removes namespace information ElementTree has added to tag -names and moves it into ``xmlns`` attributes. This typically eases -handling XML documents with namespaces considerably. If you do not -want that to happen, or want to avoid the small overhead of going -through the element structure when your XML does not have namespaces, -you can disable this feature by giving ``keep_clark_notation`` argument -a true value (see `Boolean arguments`). - -If you want to strip namespace information altogether so that it is -not included even if XML is saved, you can give a true value to -``strip_namespaces`` argument. This functionality is new in Robot -Framework 3.0.2. - -Examples: -| ${root} = | Parse XML | <root><child/></root> | -| ${xml} = | Parse XML | ${CURDIR}/test.xml | keep_clark_notation=True | -| ${xml} = | Parse XML | ${CURDIR}/test.xml | strip_namespaces=True | - -Use `Get Element` keyword if you want to get a certain element and not -the whole structure. See `Parsing XML` section for more details and -examples. - - - - - -source -xpath= -remove_tail=False - -Removes the element matching ``xpath`` from the ``source`` structure. - -The element to remove from the ``source`` is specified with ``xpath`` -using the same semantics as with `Get Element` keyword. The resulting -XML structure is returned, and if the ``source`` is an already parsed -XML structure, it is also modified in place. - -The keyword fails if ``xpath`` does not match exactly one element. -Use `Remove Elements` to remove all matched elements. - -Element's tail text is not removed by default, but that can be changed -by giving ``remove_tail`` a true value (see `Boolean arguments`). See -`Element attributes` section for more information about `tail` in -general. - -Examples using ``${XML}`` structure from `Example`: -| Remove Element | ${XML} | xpath=second | -| Element Should Not Exist | ${XML} | xpath=second | -| Remove Element | ${XML} | xpath=html/p/b | remove_tail=yes | -| Element Text Should Be | ${XML} | Text with italics. | xpath=html/p | normalize_whitespace=yes | - - - - - -source -name -xpath=. - -Removes attribute ``name`` from the specified element. - -The element whose attribute to remove is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -It is not a failure to remove a non-existing attribute. Use `Remove -Element Attributes` to remove all attributes and `Set Element Attribute` -to set them. - -Examples using ``${XML}`` structure from `Example`: -| Remove Element Attribute | ${XML} | id | xpath=first | -| Element Should Not Have Attribute | ${XML} | id | xpath=first | - -Can only remove an attribute from a single element. Use `Remove Elements -Attribute` to remove an attribute of multiple elements in one call. - - - - - -source -xpath=. - -Removes all attributes from the specified element. - -The element whose attributes to remove is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -Use `Remove Element Attribute` to remove a single attribute and -`Set Element Attribute` to set them. - -Examples using ``${XML}`` structure from `Example`: -| Remove Element Attributes | ${XML} | xpath=first | -| Element Should Not Have Attribute | ${XML} | id | xpath=first | - -Can only remove attributes from a single element. Use `Remove Elements -Attributes` to remove all attributes of multiple elements in one call. - - - - - -source -xpath= -remove_tail=False - -Removes all elements matching ``xpath`` from the ``source`` structure. - -The elements to remove from the ``source`` are specified with ``xpath`` -using the same semantics as with `Get Elements` keyword. The resulting -XML structure is returned, and if the ``source`` is an already parsed -XML structure, it is also modified in place. - -It is not a failure if ``xpath`` matches no elements. Use `Remove -Element` to remove exactly one element. - -Element's tail text is not removed by default, but that can be changed -by using ``remove_tail`` argument similarly as with `Remove Element`. - -Examples using ``${XML}`` structure from `Example`: -| Remove Elements | ${XML} | xpath=*/child | -| Element Should Not Exist | ${XML} | xpath=second/child | -| Element Should Not Exist | ${XML} | xpath=third/child | - - - - - -source -name -xpath=. - -Removes attribute ``name`` from the specified elements. - -Like `Remove Element Attribute` but removes the attribute of all -elements matching the given ``xpath``. - - - - - -source -xpath=. - -Removes all attributes from the specified elements. - -Like `Remove Element Attributes` but removes all attributes of all -elements matching the given ``xpath``. - - - - - -source -path -encoding=UTF-8 - -Saves the given element to the specified file. - -The element to save is specified with ``source`` using the same -semantics as with `Get Element` keyword. - -The file where the element is saved is denoted with ``path`` and the -encoding to use with ``encoding``. The resulting file always contains -the XML declaration. - -The resulting XML file may not be exactly the same as the original: -- Comments and processing instructions are always stripped. -- Possible doctype and namespace prefixes are only preserved when - `using lxml`. -- Other small differences are possible depending on the ElementTree - or lxml version. - -Use `Element To String` if you just need a string representation of -the element. - - - - - -source -name -value -xpath=. - -Sets attribute ``name`` of the specified element to ``value``. - -The element whose attribute to set is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -It is possible to both set new attributes and to overwrite existing. -Use `Remove Element Attribute` or `Remove Element Attributes` for -removing them. - -Examples using ``${XML}`` structure from `Example`: -| Set Element Attribute | ${XML} | attr | value | -| Element Attribute Should Be | ${XML} | attr | value | -| Set Element Attribute | ${XML} | id | new | xpath=first | -| Element Attribute Should Be | ${XML} | id | new | xpath=first | - -Can only set an attribute of a single element. Use `Set Elements -Attribute` to set an attribute of multiple elements in one call. - - - - - -source -tag -xpath=. - -Sets the tag of the specified element. - -The element whose tag to set is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -Examples using ``${XML}`` structure from `Example`: -| Set Element Tag | ${XML} | newTag | -| Should Be Equal | ${XML.tag} | newTag | -| Set Element Tag | ${XML} | xxx | xpath=second/child | -| Element Should Exist | ${XML} | second/xxx | -| Element Should Not Exist | ${XML} | second/child | - -Can only set the tag of a single element. Use `Set Elements Tag` to set -the tag of multiple elements in one call. - - - - - -source -text=None -tail=None -xpath=. - -Sets text and/or tail text of the specified element. - -The element whose text to set is specified using ``source`` and -``xpath``. They have exactly the same semantics as with `Get Element` -keyword. The resulting XML structure is returned, and if the ``source`` -is an already parsed XML structure, it is also modified in place. - -Element's text and tail text are changed only if new ``text`` and/or -``tail`` values are given. See `Element attributes` section for more -information about `text` and `tail` in general. - -Examples using ``${XML}`` structure from `Example`: -| Set Element Text | ${XML} | new text | xpath=first | -| Element Text Should Be | ${XML} | new text | xpath=first | -| Set Element Text | ${XML} | tail=& | xpath=html/p/b | -| Element Text Should Be | ${XML} | Text with bold&italics. | xpath=html/p | normalize_whitespace=yes | -| Set Element Text | ${XML} | slanted | !! | xpath=html/p/i | -| Element Text Should Be | ${XML} | Text with bold&slanted!! | xpath=html/p | normalize_whitespace=yes | - -Can only set the text/tail of a single element. Use `Set Elements Text` -to set the text/tail of multiple elements in one call. - - - - - -source -name -value -xpath=. - -Sets attribute ``name`` of the specified elements to ``value``. - -Like `Set Element Attribute` but sets the attribute of all elements -matching the given ``xpath``. - - - - - -source -tag -xpath=. - -Sets the tag of the specified elements. - -Like `Set Element Tag` but sets the tag of all elements matching -the given ``xpath``. - - - - - -source -text=None -tail=None -xpath=. - -Sets text and/or tail text of the specified elements. - -Like `Set Element Text` but sets the text or tail of all elements -matching the given ``xpath``. - - - - diff --git a/libspecs/browserstack.local_f74ac98.libspec b/libspecs/browserstack.local_f74ac98.libspec deleted file mode 100644 index 8eb48ab..0000000 --- a/libspecs/browserstack.local_f74ac98.libspec +++ /dev/null @@ -1,7 +0,0 @@ - - - -global -yes -Documentation for library ``browserstack.local``. - diff --git a/red.xml b/red.xml deleted file mode 100644 index 8a0991c..0000000 --- a/red.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - 2 - WORKSPACE - - - - - - - true - 1024 - diff --git a/web/test/parallel/0-selenium-screenshot-1.png b/web/test/parallel/0-selenium-screenshot-1.png deleted file mode 100644 index 37b3597..0000000 Binary files a/web/test/parallel/0-selenium-screenshot-1.png and /dev/null differ