BuiltIn - Documentation

Introduction

BuiltIn library provides a set of often needed generic keywords.

These keywords are available automatically without importing any library.
They allow functionality for verifications (e.g. Should Be
Equal), conversions (e.g. Convert To Integer) and for various other
purposes (e.g. Sleep).

Shortcuts

Call Method  Catenate  Comment  Convert To Boolean  Convert To Integer  Convert To Number  Convert To String  Create List  Evaluate  Fail  Get Length  Get Time  Grep  Import Library  Import Variables  Length Should Be  Log  Log Many  Log Variables  No Operation  Regexp Escape  Replace Variables  Run Keyword  Run Keyword And Expect Error  Run Keyword And Ignore Error  Run Keyword If  Run Keyword If All Critical Tests Passed  Run Keyword If All Tests Passed  Run Keyword If Any Critical Tests Failed  Run Keyword If Any Tests Failed  Run Keyword If Test Failed  Run Keyword If Test Passed  Run Keyword Unless  Set Global Variable  Set Log Level  Set Suite Variable  Set Test Variable  Set Variable  Set Variable If  Should Be Empty  Should Be Equal  Should Be Equal As Integers  Should Be Equal As Numbers  Should Be Equal As Strings  Should Be True  Should Contain  Should End With  Should Match  Should Match Regexp  Should Not Be Empty  Should Not Be Equal  Should Not Be Equal As Integers  Should Not Be Equal As Numbers  Should Not Be Equal As Strings  Should Not Be True  Should Not Contain  Should Not End With  Should Not Match  Should Not Match Regexp  Should Not Start With  Should Start With  Sleep  Syslog  Variable Should Exist  Variable Should Not Exist  Wait Until Keyword Succeeds 

Keywords

Keyword Arguments Documentation
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. In more complicated cases, the Log or Log Many keywords should
be used.
Convert To Boolean item Converts the given item to Boolean.

Handles also the strings 'True' and 'False' (case-insensitive) as
expected.
Convert To Integer item Converts the given item to an integer number.
Convert To Number item Converts the given item to a floating point number.
Convert To String item Converts the given item to a string.

Note that if the item is a Java object, its 'toString' method is called.
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
${scaler} = Create List a b c
${ints} = Create List ${1} ${2} ${3}
Evaluate expression Evaluates the given expression in Python and returns the results.

Examples (expecting ${RC} is -1):
${status} = Evaluate 0 < ${RC} < 10
${dict} = Evaluate { 'a':1, 'b':2, 'c':3 }
=>
${status} = False
${dict} = { 'a':1, 'b':2, 'c':3 }
Fail msg=None Fails the test immediately with the given message.
Get Length item Returns the length of the given item.

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

New in Robot Framework version 1.8.2.
Get Time format=timestamp Returns the current 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.

- If 'format' contains the word 'epoch', the time is returned in seconds
after the UNIX epoch. The return value is always an integer.
- 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').
- Otherwise (and by default) the time is returned as a timestamp string
in the format '2006-02-24 15:08:31'.

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'
Grep text, pattern, pattern_type=literal string Returns the text grepped using 'pattern'.

'pattern_type' defines how the given pattern is interpreted,
as explained below. It is case-insensitive and may contain other text.
For example, 'regexp', 'REGEXP' and 'Pattern is a regexp' are all
considered equal.

- If 'pattern_type' contains either the string 'simple' or 'glob', the
'pattern' is considered a simple pattern and lines returned only if
they match it. (1)
- If 'pattern_type' contains either the string 'regular expression' or
'regexp', the 'pattern' is considered a regular expression and only
lines matching it returned. (2)
- If 'pattern_type' contains the string 'case insensitive',
the 'pattern' is considered a literal string and lines returned,
if they contain the string, regardless of the case.
- Otherwise the pattern is considered a literal string and lines
returned, if they contain the string exactly. This is the default.

1) Simple pattern matching is similar to matching files in a shell, and
it is always case-sensitive. In the pattern, '*' matches to anything
and '?' matches to any single character.

2) Regular expression check is done using Python's 're' module which has
a pattern syntax derived from Perl and thus is also very similar to the
one in Java. See the following documents from more details about regexps
in general and their Python implementation in particular.

're' Module Documentation: http://docs.python.org/lib/module-re.html
Regular Expression HOWTO: http://www.amk.ca/python/howto/regex/

Note that if you want to use flags (e.g. re.IGNORECASE) you have to
embed them into the pattern (e.g. '(?i)pattern'). Note also that a
backslash is an escape character in Robot Framework test data and
possible backslaches in patterns must thus be escaped with another
backslash (e.g. '\\d\\w+').
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.
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 and path separators ('/' or '\') must
be set correctly. This is often easiest done using built-in variables
'${CURDIR}' and '${/}' as shown in the examples below.

Import Variables ${CURDIR}${/}variables.py
Import Variables ${CURDIR}${/}..${/}vars${/}env.py arg1 arg2
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.

New in Robot Framework version 1.8.2.
Log message, level=INFO Logs the given message with the given level
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 No operation.
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}

New in Robot Framework version 1.8.3.
Replace Variables text Replaces variables in the given text with their current values.

If the text contains undefined variables, this keyword fails.


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

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

Note: In versions prior to Robot Framework version 1.8.3, this keyword
only returns the return value or error message of the executed keyword.
Run Keyword If expr, name, *args Runs the given keyword with the given arguments, if 'expr' is true.

'expr' is evaluated in the same way as with the 'Should Be True'
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'.

New in Robot Framework version 1.8.3.
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 Unless expr, name, *args Runs the given keyword with the given arguments, if 'expr' is false.

See 'Run Keyword If' for more information and an example.

New in Robot Framework version 1.8.3.
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 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 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 will not see variables set with this keyword.

The variable name must be given either in the escaped format
(e.g. \${scalar} or \@{list}) or without curly braces (e.g. $scalar
or @list) to prevent it from being resolved.

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}
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 *args Returns the given arguments -- can be used to set variables.

Examples:
${var} = Set Variable Hello
${var1} ${var2} = Set Variable Hello world
@{list} = Set Variable Hi again # list variable
${scal} = Set Variable Hi again # scalar variable
=>
${var} = 'Hello'
${var1} = 'Hello' & ${var2} = 'world'
@{list} = ['Hi','again'] i.e. @{list}[0] = 'Hi' & @{list}[1] = 'again'
${scal} = ['Hi','again']
Set Variable If expr, value1, value2=None If 'expr' is true, returns 'value1', and otherwise returns 'value2'.

'expr' is evaluated as with the 'Should Be True' keyword.

Examples:
${var1} = Set Variable If 1 > 0 v1 v2
${var2} = Set Variable If False v1 v2
${var3} = Set Variable If 1 > 0 and False v1
=>
${var1} = 'v1'
${var2} = 'v2'
${var3} = None

New in Robot Framework version 1.8.3.
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.

New in Robot 1.8.2.
Should Be Equal first, second, msg=None, values=True Fails if the given objects are unequal.

- If 'msg' is not given, the possible 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 Fails if objects are unequal after converting them to integers.

See 'Should Be Equal' for an explanation on how to override the default
error message with 'msg' and 'values'.
Should Be Equal As Numbers first, second, msg=None, values=True Fails if objects are unequal after converting them to real numbers.

See '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 expr, msg=None Fails if the given expression (or item) is not true.

If 'expr' 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 ('<expr> should be true') maybe 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

New in Robot Framework version 1.8.3. This is intended to replace the
old keyword 'Fail Unless', which still continues to work.
Should Contain str1, str2, msg=None, values=True Fails if the string 'str1' does not contain the string 'str2' one or more times.

See 'Should Be Equal' for an explanation on how to override the default
error message with 'msg' and 'values'.
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 regexps
in general and Python implementation in particular.

* http://docs.python.org/lib/module-re.html
* http://www.amk.ca/python/howto/regex/

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

1) Backslash is an escape character in the test data, and possible
backslaches 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.

New in Robot Framework version 1.8.2.
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 gthe default
error message with 'msg' and 'values'.
Should Not Be Equal As Integers first, second, msg=None, values=True Fails if objects are equal after converting them to integers.

See 'Should Be Equal' for an explanation on how to override the default
error message with 'msg' and 'values'.
Should Not Be Equal As Numbers first, second, msg=None, values=True Fails if objects are equal after converting them to real numbers.

See '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 expr, msg=None Fails if the the given expression (or item) is true.

See 'Should Be True' for details about how 'expr' is evaluated and
'msg' used to override the default error message.

New in Robot Framework version 1.8.3. This is intended to replace the
old keyword 'Fail If', which still continues to work.
Should Not Contain str1, str2, msg=None, values=True Fails if the string 'str1' contains the string 'str2' one or more times.

See 'Should Be Equal' for an explanation on how to override the default
error message with 'msg' and 'values'.
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 Sleeps for the given time.

'time' may be either a number or a time string. Time strings are in
a format such as '1day 2h 3min 4s 5ms'. For more information on time
strings, see section Time format in Robot Framework User Guide.
Syslog message, level=INFO Logs the given message with the given level into syslog.
Variable Should Exist name, msg=None Fails unless a variable with the given name exists within the current scope.

The variable name must be given in the escaped format, e.g. \${scalar} or
\@{list} to prevent it from being resolved. Alternatively, in this
case, it is possible to give the variable name in a special format
without curly braces, e.g. $scalar or @list.

The default error message can be overridden with the 'msg' argument.
Variable Should Not Exist name, msg=None Fails if the variable with the given name exists within the current scope.

The variable name must be given in the escaped format, e.g. \${scalar}
or \@{list} to prevent it from being resolved. Alternatively, in this
case, it is possible to give the variable name in the special format
without curly braces, e.g. $scalar or @list.

The default error message can be overridden with the 'msg' argument.
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. 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').

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

New in Robot Framework version 1.8.1.

Altogether 66 keywords. Documentation generated 20080617 18:44:23.