libraries Package

libraries Package

Contains Robot Framework standard test libraries.

BuiltIn Module

class robot.libraries.BuiltIn.BuiltIn[source]

Bases: robot.libraries.BuiltIn._Verify, robot.libraries.BuiltIn._Converter, robot.libraries.BuiltIn._Variables, robot.libraries.BuiltIn._RunKeyword, robot.libraries.BuiltIn._Misc

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).

ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LIBRARY_VERSION = '2.7.1'
call_method(object, method_name, *args)

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.

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 | | |

catenate(*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. 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’

comment(*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.

convert_to_binary(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 |

This keyword was added in Robot Framework 2.6. See also Convert To Integer, Convert To Octal and Convert To Hex.

convert_to_boolean(item)

Converts the given item to Boolean true or false.

Handles strings ‘True’ and ‘False’ (case-insensitive) as expected, otherwise returns item’s truth value using Python’s ‘bool’ method. For more information about truth values, see http://docs.python.org/lib/truth.html.

convert_to_hex(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 giving any non-empty value to the lowercase argument turns the value (but not the 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 |

This keyword was added in Robot Framework 2.6. See also Convert To Integer, Convert To Binary and Convert To Octal.

convert_to_integer(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. Starting from Robot Framework 2.6 there are two ways to convert from other bases:

  1. Give base explicitly to the keyword as base argument.

2) 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 and Convert To Hex.

convert_to_number(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. The support for precision was added in Robot Framework 2.6.

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, this floating point arithmetic tutorial: http://docs.python.org/tutorial/floatingpoint.html

If you need an integer number, use Convert To Integer instead.

convert_to_octal(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 |

This keyword was added in Robot Framework 2.6. See also Convert To Integer, Convert To Binary and Convert To Hex.

convert_to_string(item)

Converts the given item to a Unicode string.

Uses ‘__unicode__’ or ‘__str__’ method with Python objects and ‘toString’ with Java objects.

create_list(*items)

Returns a list containing given items.

The returned list can be assigned both to ${scalar} and @{list} variables. The earlier can be used e.g. with Java keywords expecting an array as an argument.

Examples: | @{list} = | Create List | a | b | c | | ${scalar} = | Create List | a | b | c | | ${ints} = | Create List | ${1} | ${2} | ${3} |

evaluate(expression, modules=None)

Evaluates the given expression in Python and returns the results.

modules argument can be used to specify a comma separated list of Python modules to be imported and added to the namespace of the evaluated expression.

Examples (expecting ${result} is 3.14): | ${status} = | Evaluate | 0 < ${result} < 10 | | ${down} = | Evaluate | int(${result}) | | ${up} = | Evaluate | math.ceil(${result}) | math | | ${random} = | Evaluate | random.randint(0, sys.maxint) | random,sys | => | ${status} = True | ${down} = 3 | ${up} = 4.0 | ${random} = <random integer>

Notice that instead of creating complicated expressions, it is recommended to move the logic into a test library.

exit_for_loop()

Immediately stops executing the enclosing for loop.

This keyword can be used directly in a for loop or in a keyword that the for loop uses. In both cases the test execution continues after the for loop. If executed outside of a for loop, the test fails.

Example: | :FOR | ${var} | IN | @{SOME LIST} | | | Run Keyword If | ‘${var}’ == ‘EXIT’ | Exit For Loop | | | Do Something | ${var} |

New in Robot Framework 2.5.2.

fail(msg=None)

Fails the test immediately with the given (optional) message.

See Fatal Error if you need to stop the whole test execution.

fatal_error(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.

get_count(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 |

get_length(item)

Returns and logs the length of the given item.

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.

It is possible to use this keyword also with list variables (e.g. @{LIST}), but you need to use them as scalars (e.g. ${LIST}).

get_library_instance(name)

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.

get_time(format='timestamp', time_='NOW')

Returns the given time in the requested format.

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 (Jan 1, 1970 0:00:00). 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 time, but that can be altered using time argument as explained below.

  1. If time is a floating point number, it is interpreted as seconds since the epoch. This documentation is written about 1177654467 seconds after the epoch.
  2. If time is a valid 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’ (case-insensitive), the current time is used.
  4. If time is in the format ‘NOW - 1 day’ or ‘NOW + 1 hour 30 min’, the current 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 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’

${time} = | Get Time | | 1177654467 |
${secs} = | Get Time | sec | 2007-04-27 09:14:27 |
${year} = | Get Time | year | NOW | # The time of execution |
${day} = | Get Time | day | NOW - 1d | # 1 day subtraced from NOW |
@{time} = | Get Time | hour min sec | NOW + 1h 2min 3s | # 1h 2min 3s added to NOW |

=> | ${time} = ‘2007-04-27 09:14:27’ | ${secs} = 27 | ${year} = ‘2006’ | ${day} = ‘28’ | @{time} = [‘16’, ‘08’, ‘24’]

get_variable_value(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

This keyword was added in Robot Framework 2.6. See Set Variable If for another keyword to set variables dynamically.

get_variables()

Returns a dictionary containing all variables in the current scope.

import_library(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 path are used, they must be given in absolute format. Forward slashes can be used as path separators in all operating systems. It is possible to use arguments as well as to give a custom name with ‘WITH NAME’ syntax. For more information about importing libraries, see Robot Framework User Guide.

Examples: | Import Library | MyLibrary | | Import Library | ${CURDIR}/Library.py | some | args | | Import Library | ${CURDIR}/../libs/Lib.java | arg | WITH NAME | JavaLib |

import_resource(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. 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_variables(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 and this functionality can thus be used to import new variables, e.g. for each test in a test suite.

The given path must be absolute. 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 |

New in Robot Framework 2.5.4.

keyword_should_exist(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.

New in Robot Framework 2.6. See also Variable Should Exist.

length_should_be(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.

log(message, level='INFO')

Logs the given message with the given level.

Valid levels are TRACE, DEBUG, INFO (default), HTML and WARN.

The HTML level is special because it allows writing messages without HTML code in them being escaped. For example, logging a message ‘<img src=”image.png”>’ using the HTML level creates an image, but with other levels the message would be that exact string. Notice that invalid HTML can easily corrupt the whole log file so this feature should be used with care. The actual log level used for HTML messages is INFO.

Messages logged with the WARN level will be visible also in the console and in the Test Execution Errors section in the log file.

log_many(*messages)

Logs the given messages as separate entries with the INFO level.

log_variables(level='INFO')

Logs all variables in the current scope with given log level.

no_operation()

Does absolutely nothing.

regexp_escape(*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} |

remove_tags(*tags)

Removes given tags from the current test or all tests in a suite.

Tags can be given exactly or using a pattern where ‘*’ matches anything and ‘?’ matches one character.

This keyword can affect either one test case or all test cases in a test suite similarly as Set Tags keyword.

Example: | Remove Tags | mytag | something-* | ?ython |

repeat_keyword(times, name, *args)

Executes the specified keyword multiple times.

name and args define the keyword that is executed similarly as with Run Keyword, and times specifies how many the keyword should be executed. times can be given as an integer or as a string that can be converted to an integer. It can also have postfix ‘times’ or ‘x’ (case and space insensitive) to make the expression easier to read.

If times 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 | Goto Previous Page | | Repeat Keyword | ${var} | Some Keyword | arg1 | arg2 |

replace_variables(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! |
run_keyword(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.

run_keyword_and_continue_on_failure(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 |

This keyword was added in Robot Framework 2.5. The execution is not continued if the failure is caused by invalid syntax, timeout, or fatal exception.

run_keyword_and_expect_error(expected_error, name, *args)

Runs the keyword and checks that the expected error occurred.

The expected error must be given in the same format as in Robot Framework reports. It can be a pattern containing characters ‘?’, which matches to any single character and ‘*’, which matches to any number of any characters. name and *args have same semantics as with Run Keyword.

If the expected error occurs, the error message is returned and it can be further processed/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 | Some Keyword | arg1 | arg2 | | ${msg} = | Run Keyword And Expect Error | * | My KW | | Should Start With | ${msg} | Once upon a time in |

Starting from Robot Framework 2.5 errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword.

run_keyword_and_ignore_error(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 ‘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.

The keyword name and arguments work as in Run Keyword. See Run Keyword If for a usage example.

Starting from Robot Framework 2.5 errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword.

run_keyword_if(condition, name, *args)

Runs the given keyword with the given arguments, if condition is true.

The given condition is evaluated similarly as with Should Be True keyword, 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 | | 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’.

run_keyword_if_all_critical_tests_passed(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.

run_keyword_if_all_tests_passed(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.

run_keyword_if_any_critical_tests_failed(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.

run_keyword_if_any_tests_failed(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.

run_keyword_if_test_failed(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.

run_keyword_if_test_passed(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.

run_keyword_if_timeout_occurred(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.

Available in Robot Framework 2.5 and newer.

run_keyword_unless(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.

run_keywords(*names)

Executes all the given keywords in a sequence without arguments.

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 is overkill. User keywords must nevertheless be used if the executed keywords need to take arguments.

Example: | Setting | Value | Value | Value | | Suite Setup | Run Keywords | Initialize database | Start servers |

set_global_variable(name, *values)

Makes a variable available globally in all tests and suites.

Variables set with this keyword are globally available in all test cases and suites executed after setting them. Setting variables with this keyword thus has the same effect as creating from the command line using the options ‘–variable’ or ‘–variablefile’. Because this keyword can change variables everywhere, it should be used with care.

See Set Suite Variable for more information and examples.

set_library_search_order(*libraries)

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 |

Starting from Robot Framework 2.6.2 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.
  • Starting from RF 2.6.2, library and resource names in the search order are both case and space insensitive.
set_log_level(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 and NONE (no logging).

set_suite_documentation(doc)

Sets documentation for for the current suite.

The current documentation is available from built-in variable ${SUITE DOCUMENTATION}.

New in Robot Framework 2.7.

set_suite_variable(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. Other test suites, including possible child test suites, will not 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.

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 | ${GREET} | Hello, world! | | ${ID} = | Get ID | | Set Suite Variable | ${ID} |

NOTE: If the variable has value which itself is a variable (escaped or not), you must always use the escaped format to reset 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/Suite/Global Variable, Variable Should (Not) Exist, and Get Variable Value keywords.

set_tags(*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.

See Remove Tags for another keyword to modify tags at test execution time.

set_test_documentation(doc)

Sets documentation for for the current test.

The current documentation is available from built-in variable ${TEST DOCUMENTATION}. This keyword can not be used in suite setup or suite teardown.

New in Robot Framework 2.7.

set_test_message(message)

Sets message for for the current test.

This is overridden by possible failure message, except when this keyword is used in test case teardown. In test case teardown this overrides messages even for failed tests.

This keyword can not be used in suite setup or suite teardown.

set_test_variable(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.

set_variable(*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.

set_variable_if(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.

should_be_empty(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.

should_be_equal(first, second, msg=None, values=True)

Fails if the given objects are unequal.

  • If msg is not given, the error message is ‘first != second’.
  • If msg is given and values is either Boolean False or the string ‘False’ or ‘No Values’, the error message is simply msg.
  • Otherwise the error message is ‘msg: first != second‘.
should_be_equal_as_integers(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 |

should_be_equal_as_numbers(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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 this great article: http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm

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.

should_be_equal_as_strings(first, second, msg=None, values=True)

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 and values.

should_be_true(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 using the built-in ‘eval’ function and the keyword status is decided based on the result. If a non-string item is given, the status is got directly from its truth value as explained at http://docs.python.org/lib/truth.html.

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 |

should_contain(item1, item2, msg=None, values=True)

Fails if item1 does not contain item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Contain | ${output} | PASS | | Should Contain | ${some_list} | value |

should_contain_x_times(item1, item2, count, msg=None)

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.

Examples: | Should Contain X Times | ${output} | hello | 2 | | Should Contain X Times | ${some list} | value | 3 |

should_end_with(str1, str2, msg=None, values=True)

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.

should_match(string, pattern, msg=None, values=True)

Fails unless the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern, ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

should_match_regexp(string, pattern, msg=None, values=True)

Fails if string does not match pattern as a regular expression.

Regular expression check is done using the Python ‘re’ module, which has a pattern syntax derived from Perl, and thus also very similar to the one in Java. See the following documents for more details about regular expressions in general and Python implementation in particular.

Things to note about the regexp syntax in Robot Framework test data:

1) Backslash is an escape character in the test data, and possible backslashes in the pattern must thus be escaped with another backslash (e.g. ‘\d\w+’).

2) Strings that may contain special characters, but should be handled as literal strings, can be escaped with the Regexp Escape keyword.

3) 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’.

4) Possible flags altering how the expression is parsed (e.g. re.IGNORECASE, re.MULTILINE) can be set by prefixing the pattern with the ‘(?iLmsux)’ group (e.g. ‘(?im)pattern’). The available flags are ‘IGNORECASE’: ‘i’, ‘MULTILINE’: ‘m’, ‘DOTALL’: ‘s’, ‘VERBOSE’: ‘x’, ‘UNICODE’: ‘u’, and ‘LOCALE’: ‘L’.

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’

should_not_be_empty(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.

should_not_be_equal(first, second, msg=None, values=True)

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.

should_not_be_equal_as_integers(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.

should_not_be_equal_as_numbers(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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.

should_not_be_equal_as_strings(first, second, msg=None, values=True)

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.

should_not_be_true(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.

should_not_contain(item1, item2, msg=None, values=True)

Fails if item1 contains item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Not Contain | ${output} | FAILED | | Should Not Contain | ${some_list} | value |

should_not_end_with(str1, str2, msg=None, values=True)

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.

should_not_match(string, pattern, msg=None, values=True)

Fails if the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

should_not_match_regexp(string, pattern, msg=None, values=True)

Fails if string matches pattern as a regular expression.

See Should Match Regexp for more information about arguments.

should_not_start_with(str1, str2, msg=None, values=True)

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.

should_start_with(str1, str2, msg=None, values=True)

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.

sleep(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 |

variable_should_exist(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.

variable_should_not_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.

wait_until_keyword_succeeds(timeout, retry_interval, name, *args)

Waits until the specified keyword succeeds or the given timeout expires.

name and args define the keyword that is executed similarly as with Run Keyword. If the specified keyword does not succeed within timeout, this keyword fails. retry_interval is the time to wait before trying to run the keyword again after the previous run has failed.

Both timeout and retry_interval must be given in Robot Framework’s time format (e.g. ‘1 minute’, ‘2 min 3 s’, ‘4.5’).

Errors caused by invalid syntax, test or keyword timeouts, or fatal exceptions are not caught by this keyword.

Example: | Wait Until Keyword Succeeds | 2 min | 5 sec | My keyword | arg1 | arg2 |

Running the same keyword multiple times inside this keyword can create lots of output and considerably increase the size of the generated output files. Starting from Robot Framework 2.7, it is possible to remove unnecessary keywords from the outputs using –RemoveKeywords WUKS command line option.

robot.libraries.BuiltIn.register_run_keyword(library, keyword, args_to_process=None)[source]

Registers ‘run keyword’ so that its arguments can be handled correctly.

  1. Why is this method needed

Keywords running other keywords internally (normally using Run Keyword or some variants of it in BuiltIn) must have the arguments meant to the internally executed keyword handled specially to prevent processing them twice. This is done ONLY for keywords registered using this method.

If the register keyword has same name as any keyword from Robot Framework standard libraries, it can be used without getting warnings. Normally there is a warning in such cases unless the keyword is used in long format (e.g. MyLib.Keyword).

Starting from Robot Framework 2.5.2, keywords executed by registered run keywords can be tested with dryrun runmode with following limitations: - Registered keyword must have ‘name’ argument which takes keyword’s name or Registered keyword must have ‘*names’ argument which takes keywords’ names - Keyword name does not contain variables

  1. How to use this method

library is the name of the library where the registered keyword is implemented.

keyword can be either a function or method implementing the keyword, or name of the implemented keyword as a string.

args_to_process is needed when keyword is given as a string, and it defines how many of the arguments to the registered keyword must be processed normally. When keyword is a method or function, this information is got directly from it so that varargs (those specified with syntax ‘*args’) are not processed but others are.

  1. Examples

from robot.libraries.BuiltIn import BuiltIn, register_run_keyword

def my_run_keyword(name, *args):
# do something return BuiltIn().run_keyword(name, *args)

# Either one of these works register_run_keyword(__name__, my_run_keyword) register_run_keyword(__name__, ‘My Run Keyword’, 1)

from robot.libraries.BuiltIn import BuiltIn, register_run_keyword

class MyLibrary:
def my_run_keyword_if(self, expression, name, *args):
# do something return BuiltIn().run_keyword_if(expression, name, *args)

# Either one of these works register_run_keyword(‘MyLibrary’, MyLibrary.my_run_keyword_if) register_run_keyword(‘MyLibrary’, ‘my_run_keyword_if’, 2)

Collections Module

class robot.libraries.Collections.Collections[source]

Bases: robot.libraries.Collections._List, robot.libraries.Collections._Dictionary

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).

Following keywords from the BuiltIn library can also be used with lists and dictionaries: | Keyword Name | Applicable With | | Create List | lists | | Get Length | both | | Length Should Be | both | | Should Be Empty | both | | Should Not Be Empty | both | | Should Contain | lists | | Should Not Contain | lists | | Should Contain X Times | lists | | Should Not Contain X Times | lists | | Get Count | lists |

All list keywords expect a scalar variable (e.g. ${list}) as an argument. It is, however, possible to use list variables (e.g. @{list}) as scalars simply by replacing ‘@’ with ‘$’.

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 lists.

List related keywords use variables in format ${Lx} in their examples, which means a list 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}.

ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LIBRARY_VERSION = '2.7.1'
append_to_list(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’]

combine_lists(*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.

convert_to_list(item)

Converts the given item to a list.

Mainly useful for converting tuples and other iterable to lists. Use Create List from the BuiltIn library for constructing new lists.

copy_dictionary(dictionary)

Returns a copy of the given dictionary.

The given dictionary is never altered by this keyword.

copy_list(list_)

Returns a copy of the given list.

The given list is never altered by this keyword.

count_values_in_list(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 in the 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

create_dictionary(*key_value_pairs)

Creates and returns a dictionary from the given key_value_pairs.

Examples: | ${x} = | Create Dictionary | name | value | | | | ${y} = | Create Dictionary | a | 1 | b | 2 | | ${z} = | Create Dictionary | a | ${1} | b | ${2} | => - ${x} = {‘name’: ‘value’} - ${y} = {‘a’: ‘1’, ‘b’: ‘2’} - ${z} = {‘a’: 1, ‘b’: 2}

dictionaries_should_be_equal(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.

See Lists Should Be Equal for an explanation of msg. The given dictionaries are never altered by this keyword.

dictionary_should_contain_key(dictionary, key, msg=None)

Fails if key is not found from dictionary.

See List Should Contain Value for an explanation of msg.

The given dictionary is never altered by this keyword.

dictionary_should_contain_sub_dictionary(dict1, dict2, msg=None, values=True)

Fails unless all items in dict2 are found from dict1.

See Lists Should Be Equal for an explanation of msg. The given dictionaries are never altered by this keyword.

dictionary_should_contain_value(dictionary, value, msg=None)

Fails if value is not found from dictionary.

See List Should Contain Value for an explanation of msg.

The given dictionary is never altered by this keyword.

dictionary_should_not_contain_key(dictionary, key, msg=None)

Fails if key is found from dictionary.

See List Should Contain Value for an explanation of msg.

The given dictionary is never altered by this keyword.

dictionary_should_not_contain_value(dictionary, value, msg=None)

Fails if value is found from dictionary.

See List Should Contain Value for an explanation of msg.

The given dictionary is never altered by this keyword.

get_dictionary_items(dictionary)

Returns items of the given dictionary.

Items are returned sorted by keys. The given dictionary is not altered by this keyword.

Example: | ${items} = | Get Dictionary Items | ${D3} | => - ${items} = [‘a’, 1, ‘b’, 2, ‘c’, 3]

get_dictionary_keys(dictionary)

Returns keys of the given dictionary.

Keys are returned in sorted order. The given dictionary is never altered by this keyword.

Example: | ${keys} = | Get Dictionary Keys | ${D3} | => - ${keys} = [‘a’, ‘b’, ‘c’]

get_dictionary_values(dictionary)

Returns values of the given dictionary.

Values are returned sorted according to keys. The given dictionary is never altered by this keyword.

Example: | ${values} = | Get Dictionary Values | ${D3} | => - ${values} = [1, 2, 3]

get_from_dictionary(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

get_from_list(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

get_index_from_list(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 in the 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

get_slice_from_list(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 the end, use ‘None’ as the end value. ‘None’ is also a default value, so in this case, it is enough to give only start. If only end is given, start gets the value 0.

Using start or end not found on the list is the same as using the largest (or smallest) available index.

Examples (incl. Python equivelants 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

insert_into_list(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’]

keep_in_dictionary(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}

list_should_contain_sub_list(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 the use of msg and values from the Lists Should Be Equal keyword.

list_should_contain_value(list_, value, msg=None)

Fails if the value is not found from list.

If msg is not given, the default error message “[ a | b | c ] does not contain the value ‘x’” is shown in case of a failure. Otherwise, the given msg is used in case of a failure.

list_should_not_contain_duplicates(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_should_not_contain_value(list_, value, msg=None)

Fails if the value is not found from list.

See List Should Contain Value for an explanation of msg.

lists_should_be_equal(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 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 is either Boolean False or a string

‘False’ or ‘No Values’, the error message is simply msg.
  • Otherwise the error message is msg + ‘new line’ + default.

Optional names argument (new in 2.6) 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.

log_dictionary(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.

log_list(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.

remove_from_dictionary(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}

remove_from_list(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’]

remove_values_from_list(list_, *values)

Removes all occurences of given values from list.

It is not an error is a value does not exist in the list at all.

Example: | Remove Values From List | ${L4} | a | c | e | f | => - ${L4} = [‘b’, ‘d’]

reverse_list(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’]

set_list_value(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’]

set_to_dictionary(dictionary, *key_value_pairs)

Adds the given key_value_pairs to the dictionary.

Example: | Set To Dictionary | ${D1} | key | value | => - ${D1} = {‘a’: 1, ‘key’: ‘value’}

sort_list(list_)

Sorts the given list in place.

The strings are sorted alphabetically and the numbers numerically.

Note that the given list is changed and nothing is returned. Use Copy List first, if you need to keep also the original order.

${L} = [2,1,’a’,’c’,’b’] | Sort List | ${L} | => - ${L} = [1, 2, ‘a’, ‘b’, ‘c’]

DeprecatedBuiltIn Module

class robot.libraries.DeprecatedBuiltIn.DeprecatedBuiltIn[source]
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
classmethod integer(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. Starting from Robot Framework 2.6 there are two ways to convert from other bases:

  1. Give base explicitly to the keyword as base argument.

2) 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 and Convert To Hex.

classmethod float(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. The support for precision was added in Robot Framework 2.6.

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, this floating point arithmetic tutorial: http://docs.python.org/tutorial/floatingpoint.html

If you need an integer number, use Convert To Integer instead.

classmethod string(item)

Converts the given item to a Unicode string.

Uses ‘__unicode__’ or ‘__str__’ method with Python objects and ‘toString’ with Java objects.

classmethod boolean(item)

Converts the given item to Boolean true or false.

Handles strings ‘True’ and ‘False’ (case-insensitive) as expected, otherwise returns item’s truth value using Python’s ‘bool’ method. For more information about truth values, see http://docs.python.org/lib/truth.html.

classmethod list(*items)

Returns a list containing given items.

The returned list can be assigned both to ${scalar} and @{list} variables. The earlier can be used e.g. with Java keywords expecting an array as an argument.

Examples: | @{list} = | Create List | a | b | c | | ${scalar} = | Create List | a | b | c | | ${ints} = | Create List | ${1} | ${2} | ${3} |

classmethod equal(first, second, msg=None, values=True)

Fails if the given objects are unequal.

  • If msg is not given, the error message is ‘first != second’.
  • If msg is given and values is either Boolean False or the string ‘False’ or ‘No Values’, the error message is simply msg.
  • Otherwise the error message is ‘msg: first != second‘.
classmethod equals(first, second, msg=None, values=True)

Fails if the given objects are unequal.

  • If msg is not given, the error message is ‘first != second’.
  • If msg is given and values is either Boolean False or the string ‘False’ or ‘No Values’, the error message is simply msg.
  • Otherwise the error message is ‘msg: first != second‘.
classmethod fail_unless_equal(first, second, msg=None, values=True)

Fails if the given objects are unequal.

  • If msg is not given, the error message is ‘first != second’.
  • If msg is given and values is either Boolean False or the string ‘False’ or ‘No Values’, the error message is simply msg.
  • Otherwise the error message is ‘msg: first != second‘.
classmethod not_equal(first, second, msg=None, values=True)

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.

classmethod not_equals(first, second, msg=None, values=True)

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.

classmethod fail_if_equal(first, second, msg=None, values=True)

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.

classmethod is_true(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 using the built-in ‘eval’ function and the keyword status is decided based on the result. If a non-string item is given, the status is got directly from its truth value as explained at http://docs.python.org/lib/truth.html.

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 |

classmethod fail_unless(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 using the built-in ‘eval’ function and the keyword status is decided based on the result. If a non-string item is given, the status is got directly from its truth value as explained at http://docs.python.org/lib/truth.html.

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 |

classmethod is_false(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.

classmethod fail_if(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.

classmethod fail_if_ints_equal(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.

classmethod ints_not_equal(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.

classmethod ints_equal(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 |

classmethod fail_unless_ints_equal(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 |

classmethod floats_not_equal(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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.

classmethod fail_if_floats_equal(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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.

classmethod floats_equal(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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 this great article: http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm

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.

classmethod fail_unless_floats_equal(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. The support for giving precision was added in Robot Framework 2.6, in earlier versions it was hard-coded to 6.

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 this great article: http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm

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.

classmethod does_not_start(str1, str2, msg=None, values=True)

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.

classmethod fail_if_starts(str1, str2, msg=None, values=True)

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.

classmethod starts(str1, str2, msg=None, values=True)

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.

classmethod fail_unless_starts(str1, str2, msg=None, values=True)

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.

classmethod does_not_end(str1, str2, msg=None, values=True)

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.

classmethod fail_if_ends(str1, str2, msg=None, values=True)

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.

classmethod ends(str1, str2, msg=None, values=True)

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.

classmethod fail_unless_ends(str1, str2, msg=None, values=True)

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.

classmethod does_not_contain(item1, item2, msg=None, values=True)

Fails if item1 contains item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Not Contain | ${output} | FAILED | | Should Not Contain | ${some_list} | value |

classmethod fail_if_contains(item1, item2, msg=None, values=True)

Fails if item1 contains item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Not Contain | ${output} | FAILED | | Should Not Contain | ${some_list} | value |

classmethod contains(item1, item2, msg=None, values=True)

Fails if item1 does not contain item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Contain | ${output} | PASS | | Should Contain | ${some_list} | value |

classmethod fail_unless_contains(item1, item2, msg=None, values=True)

Fails if item1 does not contain item2 one or more times.

Works with strings, lists, and anything that supports Python’s ‘in’ keyword. See Should Be Equal for an explanation on how to override the default error message with msg and values.

Examples: | Should Contain | ${output} | PASS | | Should Contain | ${some_list} | value |

classmethod does_not_match(string, pattern, msg=None, values=True)

Fails if the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

classmethod fail_if_matches(string, pattern, msg=None, values=True)

Fails if the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

classmethod matches(string, pattern, msg=None, values=True)

Fails unless the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern, ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

classmethod fail_unless_matches(string, pattern, msg=None, values=True)

Fails unless the given string matches the given pattern.

Pattern matching is similar as matching files in a shell, and it is always case-sensitive. In the pattern, ‘*’ matches to anything and ‘?’ matches to any single character.

See Should Be Equal for an explanation on how to override the default error message with msg and values.

classmethod does_not_match_regexp(string, pattern, msg=None, values=True)

Fails if string matches pattern as a regular expression.

See Should Match Regexp for more information about arguments.

classmethod fail_if_regexp_matches(string, pattern, msg=None, values=True)

Fails if string matches pattern as a regular expression.

See Should Match Regexp for more information about arguments.

classmethod matches_regexp(string, pattern, msg=None, values=True)

Fails if string does not match pattern as a regular expression.

Regular expression check is done using the Python ‘re’ module, which has a pattern syntax derived from Perl, and thus also very similar to the one in Java. See the following documents for more details about regular expressions in general and Python implementation in particular.

Things to note about the regexp syntax in Robot Framework test data:

1) Backslash is an escape character in the test data, and possible backslashes in the pattern must thus be escaped with another backslash (e.g. ‘\d\w+’).

2) Strings that may contain special characters, but should be handled as literal strings, can be escaped with the Regexp Escape keyword.

3) 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’.

4) Possible flags altering how the expression is parsed (e.g. re.IGNORECASE, re.MULTILINE) can be set by prefixing the pattern with the ‘(?iLmsux)’ group (e.g. ‘(?im)pattern’). The available flags are ‘IGNORECASE’: ‘i’, ‘MULTILINE’: ‘m’, ‘DOTALL’: ‘s’, ‘VERBOSE’: ‘x’, ‘UNICODE’: ‘u’, and ‘LOCALE’: ‘L’.

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’

classmethod fail_unless_regexp_matches(string, pattern, msg=None, values=True)

Fails if string does not match pattern as a regular expression.

Regular expression check is done using the Python ‘re’ module, which has a pattern syntax derived from Perl, and thus also very similar to the one in Java. See the following documents for more details about regular expressions in general and Python implementation in particular.

Things to note about the regexp syntax in Robot Framework test data:

1) Backslash is an escape character in the test data, and possible backslashes in the pattern must thus be escaped with another backslash (e.g. ‘\d\w+’).

2) Strings that may contain special characters, but should be handled as literal strings, can be escaped with the Regexp Escape keyword.

3) 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’.

4) Possible flags altering how the expression is parsed (e.g. re.IGNORECASE, re.MULTILINE) can be set by prefixing the pattern with the ‘(?iLmsux)’ group (e.g. ‘(?im)pattern’). The available flags are ‘IGNORECASE’: ‘i’, ‘MULTILINE’: ‘m’, ‘DOTALL’: ‘s’, ‘VERBOSE’: ‘x’, ‘UNICODE’: ‘u’, and ‘LOCALE’: ‘L’.

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’

classmethod noop()

Does absolutely nothing.

classmethod set_(*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.

classmethod message(*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.

classmethod variable_exists(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.

classmethod fail_unless_variable_exists(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.

classmethod variable_does_not_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.

classmethod fail_if_variable_exists(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.

error(msg=None)[source]

Errors the test immediately with the given message.

grep(text, pattern, pattern_type='literal string')[source]

DeprecatedOperatingSystem Module

class robot.libraries.DeprecatedOperatingSystem.DeprecatedOperatingSystem[source]
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
classmethod delete_environment_variable(*names)

Deletes the specified environment variable.

Does nothing if the environment variable is not set.

Starting from Robot Framework 2.7, it is possible to remove multiple variables by passing them to this keyword as separate arguments.

classmethod environment_variable_is_set(name, msg=None)

Fails if the specified environment variable is not set.

The default error message can be overridden with the msg argument.

classmethod environment_variable_is_not_set(name, msg=None)

Fails if the specified environment variable is set.

The default error message can be overridden with the msg argument.

classmethod fail_unless_exists(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.

classmethod fail_if_exists(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.

classmethod fail_unless_file_exists(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.

classmethod fail_if_file_exists(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.

classmethod fail_unless_dir_exists(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.

classmethod fail_if_dir_exists(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.

classmethod fail_unless_dir_empty(path, msg=None)

Fails unless the specified directory is empty.

The default error message can be overridden with the msg argument.

classmethod fail_if_dir_empty(path, msg=None)

Fails if the specified directory is empty.

The default error message can be overridden with the msg argument.

classmethod fail_unless_file_empty(path, msg=None)

Fails unless the specified file is empty.

The default error message can be overridden with the msg argument.

classmethod fail_if_file_empty(path, msg=None)

Fails if the specified directory is empty.

The default error message can be overridden with the msg argument.

classmethod empty_dir(path)

Deletes all the content (incl. subdirectories) from the given directory.

classmethod remove_dir(path, recursive=False)

Removes the directory pointed to by the given path.

If the second argument recursive is set to any non-empty string, 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.

classmethod copy_dir(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.

classmethod move_dir(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.

classmethod create_dir(path)

Creates the specified directory.

Also possible intermediate directories are created. Passes if the directory already exists, and fails if the path points to a regular file.

classmethod list_dir(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.

By default, the file and directory names are returned relative to the given path (e.g. ‘file.txt’). If you want them be returned in the absolute format (e.g. ‘/home/robot/file.txt’), set the absolute argument to any non-empty string.

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} | ??? |

classmethod list_files_in_dir(path, pattern=None, absolute=False)

A wrapper for List Directory that returns only files.

classmethod list_dirs_in_dir(path, pattern=None, absolute=False)

A wrapper for List Directory that returns only directories.

classmethod count_items_in_dir(path, pattern=None)

Returns and logs the number of all items in the given directory.

The argument pattern has the same semantics as in the 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.

classmethod count_files_in_dir(path, pattern=None)

A wrapper for Count Items In Directory returning only file count.

classmethod count_dirs_in_dir(path, pattern=None)

A wrapper for Count Items In Directory returning only directory count.

Dialogs Module

Easter Module

robot.libraries.Easter.none_shall_pass(who)[source]

OperatingSystem Module

class robot.libraries.OperatingSystem.OperatingSystem[source]

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).

Pattern matching

Some keywords allow their arguments to be specified as _glob patterns_ where: | * | matches anything, even an empty string | | ? | 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 |

Unless otherwise noted, matching is case-insensitive on case-insensitive operating systems such as Windows. Pattern matching is implemented using Python’s fnmatch module: http://docs.python.org/library/fnmatch.html

Path separators

All keywords expecting paths as arguments accept a forward slash (/) as a path separator regardless the operating system. Notice that this does not work when the path is part of an argument, like it often is with Run and Start Process keywords. In such cases the built-in variable ${/} can be used to keep the test data platform independent.

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} | ${TEMPDIR}/stuff |
| ${output} = | Run | ${CURDIR}${/}script.py arg |
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LIBRARY_VERSION = '2.7.1'
run(command)[source]

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 |

run_and_return_rc(command)[source]

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.

run_and_return_rc_and_output(command)[source]

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 |

start_process(command, stdin=None, alias=None)[source]

Starts the given command as a background process.

Starts the process in the background and sets this process as the current process. The following calls of the keywords Read Process Output or Stop Process affect this process, unless the keyword Switch Process is used.

If the command needs input through the standard input stream, it can be defined with the stdin argument. It is not possible to give input to the command later. Possible command line arguments must be given as part of the command like ‘/tmp/script.sh arg1 arg2’.

Returns the index of this process. The indexing starts from 1, and it can be used to switch between the processes with the Switch Process keyword. To end all processes and reset indexing, the Stop All Processes keyword must be used.

The optional alias is a name for this process that may be used with Switch Process instead of the returned index.

The standard error stream is redirected to the standard input stream automatically by adding ‘2>&1’ after the executed command. This is done the same way, and for the same reasons, as with Run keyword.

Example: | Start Process | /path/longlasting.sh | | Do Something | | | ${output} = | Read Process Output | | Should Contain | ${output} | Expected text | | [Teardown] | Stop All Processes |

switch_process(index_or_alias)[source]

Switches the active process to the specified process.

The index is the return value of the Start Process keyword and an alias may have been defined to it.

Example: | Start Process | /path/script.sh arg | | 1st process | | ${2nd} = | Start Process | /path/script2.sh | | Switch Process | 1st process | | ${out1} = | Read Process Output | | Switch Process | ${2nd} | | ${out2} = | Read Process Output | | Log Many | 1st process: ${out1} | 2nd process: ${out1} | | [Teardown] | Stop All Processes |

read_process_output()[source]

Waits for the process to finish and returns its output.

As mentioned in the documentation of Start Process keyword, and documented thoroughly in Run keyword, the standard error stream is automatically redirected to the standard output. This keyword thus always returns all the output procuded by the command.

Note that although the process is finished, it is not removed from the process list. Trying to read from a stopped process nevertheless fails. To reset the process list (and indexes and aliases), Stop All Processes must be used.

See Start Process and Switch Process for more information and examples about running processes.

stop_process()[source]

Stops the current process without reading from it.

Stopping a process does not remove it from the process list. To reset the process list (and indexes and aliases), Stop All Processes must be used. Stopping an already stopped process has no effect.

See Start Process and Switch Process for more information.

stop_all_processes()[source]

Stops all the processes and removes them from the process list.

Resets the indexing that Start Process uses. All aliases are also deleted. It does not matter have some of the processes already been closed or not.

It is highly recommended to use this keyword in test or suite level teardown to make sure all the started processes are closed.

get_file(path, encoding='UTF-8')[source]

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. By default the value is ‘UTF-8’, which means that UTF-8 and ASCII-encoded files are read correctly.

get_binary_file(path)[source]

Returns the contents of a specified file.

This keyword reads the specified file and returns the contents as is. See also Get File.

New in Robot Framework 2.5.5.

grep_file(path, pattern, encoding='UTF-8')[source]

Returns the lines of the specified file that match the pattern.

This keyword reads a file from the file system using the defined path and encoding 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.

log_file(path, encoding='UTF-8')[source]

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.

should_exist(path, msg=None)[source]

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.

should_not_exist(path, msg=None)[source]

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.

file_should_exist(path, msg=None)[source]

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.

file_should_not_exist(path, msg=None)[source]

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.

directory_should_exist(path, msg=None)[source]

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.

directory_should_not_exist(path, msg=None)[source]

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.

wait_until_removed(path, timeout='1 minute')[source]

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.

wait_until_created(path, timeout='1 minute')[source]

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.

directory_should_be_empty(path, msg=None)[source]

Fails unless the specified directory is empty.

The default error message can be overridden with the msg argument.

directory_should_not_be_empty(path, msg=None)[source]

Fails if the specified directory is empty.

The default error message can be overridden with the msg argument.

file_should_be_empty(path, msg=None)[source]

Fails unless the specified file is empty.

The default error message can be overridden with the msg argument.

file_should_not_be_empty(path, msg=None)[source]

Fails if the specified directory is empty.

The default error message can be overridden with the msg argument.

create_file(path, content='', encoding='UTF-8')[source]

Creates a file with the given content and encoding.

If the directory where to create file does not exist it, and possible intermediate missing directories, are created.

Use Append To File if you want to append to an existing file, and use File Should Not Exist if you want to avoid overwriting existing files.

append_to_file(path, content, encoding='UTF-8')[source]

Appends the given contend to the specified file.

If the file does not exists, this keyword works exactly the same way as Create File With Encoding.

remove_file(path)[source]

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.

remove_files(*paths)[source]

Uses Remove File to remove multiple files one-by-one.

Example: | Remove Files | ${TEMPDIR}${/}foo.txt | ${TEMPDIR}${/}bar.txt | ${TEMPDIR}${/}zap.txt |

empty_directory(path)[source]

Deletes all the content (incl. subdirectories) from the given directory.

create_directory(path)[source]

Creates the specified directory.

Also possible intermediate directories are created. Passes if the directory already exists, and fails if the path points to a regular file.

remove_directory(path, recursive=False)[source]

Removes the directory pointed to by the given path.

If the second argument recursive is set to any non-empty string, 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.

copy_file(source, destination)[source]

Copies the source file into a new destination.

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 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.

move_file(source, destination)[source]

Moves the source file into a new destination.

Uses Copy File keyword internally, and source and destination arguments have exactly same semantics as with that keyword.

copy_directory(source, destination)[source]

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.

move_directory(source, destination)[source]

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.

get_environment_variable(name, default=None)[source]

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.

Starting from Robot Framework 2.7, 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}.

set_environment_variable(name, value)[source]

Sets an environment variable to a specified value.

Values are converted to strings automatically. Starting from Robot Framework 2.7, set variables are automatically encoded using the system encoding.

remove_environment_variable(*names)[source]

Deletes the specified environment variable.

Does nothing if the environment variable is not set.

Starting from Robot Framework 2.7, it is possible to remove multiple variables by passing them to this keyword as separate arguments.

environment_variable_should_be_set(name, msg=None)[source]

Fails if the specified environment variable is not set.

The default error message can be overridden with the msg argument.

environment_variable_should_not_be_set(name, msg=None)[source]

Fails if the specified environment variable is set.

The default error message can be overridden with the msg argument.

get_environment_variables()[source]

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.

New in Robot Framework 2.7.

log_environment_variables(level='INFO')[source]

Logs all environment variables using the given log level.

Environment variables are also returned the same way as with Get Environment Variables keyword.

New in Robot Framework 2.7.

join_path(base, *parts)[source]

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’

join_paths(base, *paths)[source]

Joins given paths with base and returns resulted paths.

See Join Path for more information.

Examples: | @{p1} = | Join Path | base | example | other | | | @{p2} = | Join Path | /my/base | /example | other | | | @{p3} = | Join Path | 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’]

normalize_path(path)[source]

Normalizes the given path.

Examples: | ${path} = | Normalize Path | abc | | ${p2} = | Normalize Path | abc/ | | ${p3} = | Normalize Path | abc/../def | | ${p4} = | Normalize Path | abc/./def | | ${p5} = | Normalize Path | abc//def | => - ${path} = ‘abc’ - ${p2} = ‘abc’ - ${p3} = ‘def’ - ${p4} = ‘abc/def’ - ${p5} = ‘abc/def’

split_path(path)[source]

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’

split_extension(path)[source]

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} = ‘’

get_modified_time(path, format='timestamp')[source]

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 the ${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’]

set_modified_time(path, mtime)[source]

Sets the file modification time.

Changes the modification and access times of the given file to the value determined by mtime, which can be given in four different ways.

  1. If mtime is a floating point number, it is interpreted as seconds since epoch (Jan 1, 1970 0:00:00). This documentation is written about 1177654467 seconds since epoch.
  2. If mtime is a valid 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’ (case-insensitive), the current time is used.
  4. If mtime is in the format ‘NOW - 1 day’ or ‘NOW + 1 hour 30 min’, the current 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 | #(2007-04-27 9:14:27) | | Set Modified Time | /path/file | 2007-04-27 9:14:27 | | Set Modified Time | /path/file | NOW | # The time of execution | | Set Modified Time | /path/file | NOW - 1d | # 1 day subtracted from NOW | | Set Modified Time | /path/file | NOW + 1h 2min 3s | # 1h 2min 3s added to NOW |

get_file_size(path)[source]

Returns and logs file size as an integer in bytes

list_directory(path, pattern=None, absolute=False)[source]

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.

By default, the file and directory names are returned relative to the given path (e.g. ‘file.txt’). If you want them be returned in the absolute format (e.g. ‘/home/robot/file.txt’), set the absolute argument to any non-empty string.

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} | ??? |

list_files_in_directory(path, pattern=None, absolute=False)[source]

A wrapper for List Directory that returns only files.

list_directories_in_directory(path, pattern=None, absolute=False)[source]

A wrapper for List Directory that returns only directories.

count_items_in_directory(path, pattern=None)[source]

Returns and logs the number of all items in the given directory.

The argument pattern has the same semantics as in the 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.

count_files_in_directory(path, pattern=None)[source]

A wrapper for Count Items In Directory returning only file count.

count_directories_in_directory(path, pattern=None)[source]

A wrapper for Count Items In Directory returning only directory count.

touch(path)[source]

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.

Remote Module

class robot.libraries.Remote.Remote(uri='http://localhost:8270')[source]
ROBOT_LIBRARY_SCOPE = 'TEST SUITE'
get_keyword_names(attempts=5)[source]
get_keyword_arguments(name)[source]
get_keyword_documentation(name)[source]
run_keyword(name, args)[source]
class robot.libraries.Remote.RemoteResult(result)[source]
class robot.libraries.Remote.XmlRpcRemoteClient(uri)[source]
get_keyword_names()[source]
get_keyword_arguments(name)[source]
get_keyword_documentation(name)[source]
run_keyword(name, args)[source]

Reserved Module

class robot.libraries.Reserved.Reserved[source]
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
get_keyword_names()[source]
run_keyword(name, args)[source]

Screenshot Module

class robot.libraries.Screenshot.Screenshot(screenshot_directory=None)[source]

Bases: object

A test library for taking screenshots and embedding them into log files.

Using with Jython

On Jython this library uses Java AWT APIs. They are always available and thus no external modules are needed.

Using with Python

On Python you need to have one of the following modules installed to be able to use this library. The first module that is found will be used.

Python support was added in Robot Framework 2.5.5.

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 in importing and Set Screenshot Directory

keyword during execution. It is also possible to save screenshots using an absolute path.

Note that prior to Robot Framework 2.5.5 the default screenshot location was system’s temporary directory.

Changes in Robot Framework 2.5.5 and Robot Framework 2.6

This library was heavily enhanced in Robot Framework 2.5.5 release. The changes are listed below and explained more thoroughly in affected places.

  • The support for using this library on Python (see above) was added.
  • The default location where screenshots are saved was changed (see above).
  • New Take Screenshot and Take Screenshot Without Embedding keywords were added. These keywords should be used for taking screenshots in the future. Other screenshot taking keywords will be deprecated and removed later.
  • log_file_directory argument was deprecated everywhere it was used.

In Robot Framework 2.6, following additional changes were made:

  • log_file_directory argument was removed altogether.
  • Set Screenshot Directories keyword was removed.
  • Save Screenshot, Save Screenshot To and Log Screenshot keywords were deprecated. They will be removed in Robot Framework 2.8.

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.

Examples (use only one of these):

Setting | Value | Value | Value |
Library | Screenshot | | # Default location |
Library | Screenshot | ${TEMPDIR} | # System temp (this was default prior to 2.5.5) |
ROBOT_LIBRARY_SCOPE = 'TEST SUITE'
ROBOT_LIBRARY_VERSION = '2.7.1'
set_screenshot_directory(path)[source]

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.

save_screenshot_to(path)[source]

DEPRECATED Use Take Screenshot or Take Screenshot Without Embedding instead.

save_screenshot(basename='screenshot', directory=None)[source]

DEPRECATED Use Take Screenshot or Take Screenshot Without Embedding instead.

log_screenshot(basename='screenshot', directory=None, width='100%')[source]

DEPRECATED Use Take Screenshot or Take Screenshot Without Embedding instead.

take_screenshot(name='screenshot', width='800px')[source]

Takes a screenshot and embeds it into the log file.

Name of the file where the screenshot is stored is derived from name. If name ends with extension .jpg or .jpeg, the screenshot will be stored with that name. Otherwise a unique name is created by adding underscore, a running index and 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.

width specifies the size of the screenshot in the log file.

The path where the screenshot is saved is returned.

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. |

Screenshots can be only taken in JPEG format. It is possible to use / as a path separator in all operating systems.

take_screenshot_without_embedding(name='screenshot')[source]

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.

class robot.libraries.Screenshot.ScreenshotTaker(module_name=None)[source]

Bases: object

String Module

class robot.libraries.String.String[source]

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 the BuiltIn library can also be used with strings: - Catenate - Get Length - Length Should Be - Should (Not) Match (Regexp) - Should (Not) Be Empty - Should (Not) Be Equal (As Strings/Integers/Numbers) - Should (Not) Contain - Should (Not) Start With - Should (Not) End With

ROBOT_LIBRARY_SCOPE = 'GLOBAL'
ROBOT_LIBRARY_VERSION = '2.7.1'
get_line_count(string)[source]

Returns and logs the number of lines in the given string.

split_to_lines(string, start=0, end=None)[source]

Converts the string into a list of 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.

get_line(string, line_number)[source]

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 |

get_lines_containing_string(string, pattern, case_insensitive=False)[source]

Returns lines of the given string that contain the pattern.

The pattern is always considered to be a normal string and a line matches if the pattern is found anywhere in it. By default the match is case-sensitive, but setting case_insensitive to any value makes it case-insensitive.

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.

get_lines_matching_pattern(string, pattern, case_insensitive=False)[source]

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. By default the match is case-sensitive, but setting case_insensitive to any value makes it case-insensitive.

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 |

See Get Lines Matching Regexp if you need more complex patterns and Get Lines Containing String if searching literal strings is enough.

get_lines_matching_regexp(string, pattern)[source]

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. A line matches only if it matches the pattern fully. Notice that to make the match case-insensitive, you need to embed case-insensitive flag into the pattern.

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 Regexp | ${result} | Reg\w{3} example | | ${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).

replace_string(string, search_for, replace_with, count=-1)[source]

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 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 | ${str} | Hello | Hi | | | ${str} = | Replace String | ${str} | world | tellus | 1 |

replace_string_using_regexp(string, pattern, replace_with, count=-1)[source]

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.

Examples: | ${str} = | Replace String Using Regexp | ${str} | (Hello|Hi) | Hei | | | ${str} = | Replace String Using Regexp | ${str} | 20\d\d-\d\d-\d\d | <DATE> | 2 |

split_string(string, separator=None, max_split=-1)[source]

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.

split_string_from_right(string, separator=None, max_split=-1)[source]

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} | ${others} = | Split String | ${string} | - | 1 | | ${others} | ${last} = | Split String From Right | ${string} | - | 1 |

split_string_to_characters(string)[source]

Splits the string` to characters.

Example: | @{characters} = | Split String To Characters | ${string} |

fetch_from_left(string, marker)[source]

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.

fetch_from_right(string, marker)[source]

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.

generate_random_string(length=8, chars='[LETTERS][NUMBERS]')[source]

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:

_[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 |

get_substring(string, start, end=None)[source]

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 | |

should_be_string(item, msg=None)[source]

Fails if the given item is not a string.

The default error message can be overridden with the optional msg argument.

should_not_be_string(item, msg=None)[source]

Fails if the given item is a string.

The default error message can be overridden with the optional msg argument.

should_be_lowercase(string, msg=None)[source]

Fails if the given string is not in lowercase.

The default error message can be overridden with the optional msg argument.

For example ‘string’ and ‘with specials!’ would pass, and ‘String’, ‘’ and ‘ ‘ would fail.

See also Should Be Uppercase and Should Be Titlecase. All these keywords were added in Robot Framework 2.1.2.

should_be_uppercase(string, msg=None)[source]

Fails if the given string is not in uppercase.

The default error message can be overridden with the optional msg argument.

For example ‘STRING’ and ‘WITH SPECIALS!’ would pass, and ‘String’, ‘’ and ‘ ‘ would fail.

See also Should Be Titlecase and Should Be Lowercase. All these keywords were added in Robot Framework 2.1.2.

should_be_titlecase(string, msg=None)[source]

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.

The default error message can be overridden with the optional msg argument.

For example ‘This Is Title’ would pass, and ‘Word In UPPER’, ‘Word In lower’, ‘’ and ‘ ‘ would fail.

See also Should Be Uppercase and Should Be Lowercase. All theses keyword were added in Robot Framework 2.1.2.

Telnet Module

class robot.libraries.Telnet.Telnet(timeout=3.0, newline='CRLF', prompt=None, prompt_is_regexp=False)[source]

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.

See Open Connection and Switch Connection for details on how to handle multiple simultaneous connections. The responses are expected to be ASCII encoded and all non-ASCII characters are silently ignored.

Telnet library can be imported with optional arguments.

Initialization parameters are used as default values when new connections are opened with Open Connection keyword. They can also be set after opening the connection using the Set Timeout, Set Newline and Set Prompt keywords. See these keywords for more information.

Examples (use only one of these):

Setting | Value | Value | Value | Value | Value | Comment |
Library | Telnet | | | | | # default values |
Library | Telnet | 0.5 | | | | # set only timeout |
Library | Telnet | | LF | | | # set only newline |
Library | Telnet | 2.0 | LF | | | # set timeout and newline |
Library | Telnet | 2.0 | CRLF | $ | | # set also prompt |
Library | Telnet | 2.0 | LF | ($|~) | True | # set prompt with simple regexp |
ROBOT_LIBRARY_SCOPE = 'TEST_SUITE'
ROBOT_LIBRARY_VERSION = '2.7.1'
get_keyword_names()[source]
open_connection(host, alias=None, port=23, timeout=None, newline=None, prompt=None, prompt_is_regexp=False)[source]

Opens a new Telnet connection to the given host and port.

Possible already opened connections are cached.

Returns the index of this connection, which can be used later to switch back to the connection. The index starts from 1 and is reset back to it when the Close All Connections keyword is used.

The optional alias is a name for the connection, and it can be used for switching between connections, similarly as the index. See Switch Connection for more details about that.

The timeout, newline, prompt and prompt_is_regexp arguments get default values when the library is taken into use, but setting them here overrides those values for this connection. See importing for more information.

switch_connection(index_or_alias)[source]

Switches between active connections using an index or alias.

The index is got from Open Connection keyword, and an alias can be given to it.

Returns the index of previously 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 again | | [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.

${id} = | Open Connection | myhost.net |
# Do something ... | | |
Switch Connection | ${id} | |
close_all_connections()[source]

Closes all open connections and empties the connection cache.

After this keyword, new indexes got from the Open Connection keyword are reset to 1.

This keyword should be used in a test or suite teardown to make sure all connections are closed.

class robot.libraries.Telnet.TelnetConnection(host=None, port=23, timeout=3.0, newline='CRLF', prompt=None, prompt_is_regexp=False)[source]

Bases: telnetlib.Telnet

set_timeout(timeout)[source]

Sets the timeout used in read operations to the given value.

timeout is given in Robot Framework’s time format (e.g. 1 minute 20 seconds) that is explained in the User Guide.

Read operations that expect some output to appear (Read Until, Read Until Regexp, Read Until Prompt) use this timeout and fail if the expected output has not appeared when this timeout expires.

The old timeout is returned and can be used to restore it later.

Example: | ${tout} = | Set Timeout | 2 minute 30 seconds | | Do Something | | Set Timeout | ${tout} |

set_newline(newline)[source]

Sets the newline used by the Write keyword.

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 |

Correct newline to use depends on the system and the default value is ‘CRLF’.

The old newline is returned and can be used to restore it later. See Set Prompt or Set Timeout for an example.

close_connection(loglevel=None)[source]

Closes the current Telnet connection and returns any remaining output.

See Read for more information on loglevel.

login(username, password, login_prompt='login: ', password_prompt='Password: ')[source]

Logs in to the Telnet server with the given user information.

The login keyword reads from the connection until login_prompt is encountered and then types the user name. Then it reads until password_prompt is encountered and types the password. The rest of the output (if any) is also read, and all the text that has been read is returned as a single string.

If a prompt has been set to this connection, either with Open Connection or Set Prompt, this keyword reads the output until the prompt is found. Otherwise, the keyword sleeps for a second and reads everything that is available.

write(text, loglevel=None)[source]

Writes the given text over the connection and appends a newline.

Consumes the written text (until the appended newline) from the output and returns it. The given text must not contain newlines.

Note: This keyword does not return the possible output of the executed command. To get the output, one of the Read XXX keywords must be used.

See Read for more information on loglevel.

write_bare(text)[source]

Writes the given text over the connection without appending a newline.

Does not consume the written text.

write_until_expected_output(text, expected, timeout, retry_interval, loglevel=None)[source]

Writes the given text repeatedly, until expected appears in the output.

text is written without appending a newline. retry_interval defines the time waited before writing text again. text is consumed from the output before expected is tried to be read.

If expected does not appear in the output within timeout, this keyword fails.

See Read for more information on loglevel.

Example: | Write Until Expected Output | ps -ef| grep myprocessn | myprocess | | ... | 5s | 0.5s |

This writes the ‘ps -ef | grep myprocessn’, until ‘myprocess’ appears on 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.

read(loglevel=None)[source]

Reads and returns/logs everything that is currently available in the output.

The read message is always returned and logged. The default log level is either ‘INFO’, or the level set with Set Default Log Level. loglevel can be used to override the default log level, and the available levels are TRACE, DEBUG, INFO, and WARN.

read_until(expected, loglevel=None)[source]

Reads from the current output, until expected is encountered.

Text up to and including the match is returned. If no match is found, the keyword fails.

See Read for more information on loglevel.

read_until_regexp(*expected)[source]

Reads from the current output, until a match to a regexp in expected.

Expected is a list of regular expression patterns as strings, or compiled regular expressions. The keyword returns the text up to and including the first match to any of the regular expressions.

If the last argument in *expected is a valid log level, it is used as loglevel in the keyword Read.

Examples: | Read Until Regexp | (#|$) | | Read Until Regexp | first_regexp | second_regexp | | Read Until Regexp | some regexp | DEBUG |

read_until_prompt(loglevel=None)[source]

Reads from the current output, until a prompt is found.

The prompt must have been set, either in the library import or at login time, or by using the Set Prompt keyword.

See Read for more information on loglevel.

execute_command(command, loglevel=None)[source]

Executes given command and reads and returns everything until prompt.

This is a convenience keyword; following two are functionally identical:

${out} = | Execute Command | Some command |
Write | Some command |
${out} = | Read Until Prompt |

This keyword expects a prompt to be set, see Read Until Prompt for details.

See Read for more information on loglevel.

set_prompt(prompt, prompt_is_regexp=False)[source]

Sets the prompt used in this connection to prompt.

If prompt_is_regexp is a non-empty string, the given prompt is considered to be a regular expression.

The old prompt is returned and can be used to restore it later.

Example: | ${prompt} | ${regexp} = | Set Prompt | $ | | Do Something | | Set Prompt | ${prompt} | ${regexp} |

set_default_log_level(level)[source]

Sets the default log level used by all read keywords.

The possible values are TRACE, DEBUG, INFO and WARN. The default is INFO. The old value is returned and can be used to restore it later, similarly as with Set Timeout.

close()

Close the connection.

expect(list, timeout=None)

Read until one from a list of a regular expressions matches.

The first argument is a list of regular expressions, either compiled (re.RegexObject instances) or uncompiled (strings). The optional second argument is a timeout, in seconds; default is no timeout.

Return a tuple of three items: the index in the list of the first regular expression that matches; the match object returned; and the text read up till and including the match.

If EOF is read and no text was read, raise EOFError. Otherwise, when nothing matches, return (-1, None, text) where text is the text received so far (may be the empty string if a timeout happened).

If a regular expression ends with a greedy match (e.g. ‘.*’) or if more than one expression can match the same input, the results are undeterministic, and may depend on the I/O timing.

fileno()

Return the fileno() of the socket object used internally.

fill_rawq()

Fill raw queue from exactly one recv() system call.

Block if no data is immediately available. Set self.eof when connection is closed.

get_socket()

Return the socket object used internally.

interact()

Interaction function, emulates a very dumb telnet client.

listener()

Helper for mt_interact() – this executes in the other thread.

msg(msg, *args)

Print a debug message, when the debug level is > 0.

If extra arguments are present, they are substituted in the message using the standard string formatting operator.

mt_interact()

Multithreaded version of interact().

open(host, port=0, timeout=<object object at 0x7f47e9afa2d0>)

Connect to a host.

The optional second argument is the port number, which defaults to the standard telnet port (23).

Don’t try to reopen an already connected instance.

process_rawq()

Transfer from raw queue to cooked queue.

Set self.eof when connection is closed. Don’t block unless in the midst of an IAC sequence.

rawq_getchar()

Get next char from raw queue.

Block if no data is immediately available. Raise EOFError when connection is closed.

read_all()

Read all data until EOF; block until connection closed.

read_eager()

Read readily available data.

Raise EOFError if connection closed and no cooked data available. Return ‘’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.

read_lazy()

Process and return data that’s already in the queues (lazy).

Raise EOFError if connection closed and no data available. Return ‘’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.

read_sb_data()

Return any data available in the SB ... SE queue.

Return ‘’ if no SB ... SE available. Should only be called after seeing a SB or SE command. When a new SB command is found, old unread SB data will be discarded. Don’t block.

read_some()

Read at least one byte of cooked data unless EOF is hit.

Return ‘’ if EOF is hit. Block if no data is immediately available.

read_very_eager()

Read everything that’s possible without blocking in I/O (eager).

Raise EOFError if connection closed and no cooked data available. Return ‘’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.

read_very_lazy()

Return any data available in the cooked queue (very lazy).

Raise EOFError if connection closed and no data available. Return ‘’ if no cooked data available otherwise. Don’t block.

set_debuglevel(debuglevel)

Set the debug level.

The higher it is, the more debug output you get (on sys.stdout).

set_option_negotiation_callback(callback)

Provide a callback function called after each receipt of a telnet option.

sock_avail()

Test whether data is available on the socket.

dialogs_jy Module

dialogs_py Module