An always available standard library with often needed keywords.
BuiltIn
is Robot Framework's standard library that provides a set of generic keywords needed often. It is imported automatically and thus always available. The provided keywords can be used, for example, for verifications (e.g. Should Be Equal, Should Contain), conversions (e.g. Convert To Integer) and for various other purposes (e.g. Log, Sleep, Run Keyword If, Set Global Variable).
Table of contents
- HTML error messages
- Evaluating expressions
- Boolean arguments
- Pattern matching
- Multiline string comparison
- String representations
- Shortcuts
- Keywords
HTML error messages
Many of the keywords accept an optional error message to use if the keyword fails, and it is possible to use HTML in these messages by prefixing them with *HTML*
. See Fail keyword for a usage example. Notice that using HTML in messages is not limited to BuiltIn library but works with any error message.
Evaluating expressions
Many keywords, such as Evaluate, Run Keyword If and Should Be True, accept an expression that is evaluated in Python.
Evaluation namespace
Expressions are evaluated using Python's eval function so that all Python built-ins like len()
and int()
are available. In addition to that, all unrecognized variables are considered to be modules that are automatically imported. It is possible to use all available Python modules, including the standard modules and the installed third party modules.
Examples:
Should Be True | len('${result}') > 3 | |
Run Keyword If | os.sep == '/' | Non-Windows Keyword |
${robot version} = | Evaluate | robot.__version__ |
Evaluate also allows configuring the execution namespace with a custom namespace and with custom modules to be imported. The latter functionality is useful when using nested modules like rootmod.submod
that are implemented so that the root module does not automatically import sub modules. Otherwise the automatic module import mechanism described earlier is enough to get the needed modules imported.
NOTE: Automatic module import is a new feature in Robot Framework 3.2. Earlier modules needed to be explicitly taken into use when using the Evaluate keyword and other keywords only had access to sys
and os
modules.
Using variables
When a variable is used in the expressing using the normal ${variable}
syntax, its value is replaced before the expression is evaluated. This means that the value used in the expression will be the string representation of the variable value, not the variable value itself. This is not a problem with numbers and other objects that have a string representation that can be evaluated directly, but with other objects the behavior depends on the string representation. Most importantly, strings must always be quoted, and if they can contain newlines, they must be triple quoted.
Examples:
Should Be True | ${rc} < 10 | Return code greater than 10 | |
Run Keyword If | '${status}' == 'PASS' | Log | Passed |
Run Keyword If | 'FAIL' in '''${output}''' | Log | Output contains FAIL |
Actual variables values are also available in the evaluation namespace. They can be accessed using special variable syntax without the curly braces like $variable
. These variables should never be quoted.
Examples:
Should Be True | $rc < 10 | Return code greater than 10 | |
Run Keyword If | $status == 'PASS' | Log | Passed |
Run Keyword If | 'FAIL' in $output | Log | Output contains FAIL |
Should Be True | len($result) > 1 and $result[1] == 'OK' | ||
Should Be True | $result is not None |
Using the $variable
syntax slows down expression evaluation a little. This should not typically matter, but should be taken into account if complex expressions are evaluated often and there are strict time constrains.
Notice that instead of creating complicated expressions, it is often better to move the logic into a test library. That eases maintenance and can also enhance execution speed.
Boolean arguments
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to FALSE
, NONE
, NO
, OFF
or 0
, case-insensitively. Keywords verifying something that allow dropping actual and expected values from the possible error message also consider string no values
to be false. Other strings are considered true unless the keyword documentation explicitly states otherwise, and other argument types are tested using the same rules as in Python.
True examples:
Should Be Equal | ${x} | ${y} | Custom error | values=True | # Strings are generally true. |
Should Be Equal | ${x} | ${y} | Custom error | values=yes | # Same as the above. |
Should Be Equal | ${x} | ${y} | Custom error | values=${TRUE} | # Python True is true. |
Should Be Equal | ${x} | ${y} | Custom error | values=${42} | # Numbers other than 0 are true. |
False examples:
Should Be Equal | ${x} | ${y} | Custom error | values=False | # String false is false. |
Should Be Equal | ${x} | ${y} | Custom error | values=no | # Also string no is false. |
Should Be Equal | ${x} | ${y} | Custom error | values=${EMPTY} | # Empty string is false. |
Should Be Equal | ${x} | ${y} | Custom error | values=${FALSE} | # Python False is false. |
Should Be Equal | ${x} | ${y} | Custom error | values=no values | # no values works with values argument |
Considering string NONE
false is new in Robot Framework 3.0.3 and considering also OFF
and 0
false is new in Robot Framework 3.1.
Pattern matching
Many keywords accepts arguments as either glob or regular expression patterns.
Glob patterns
Some keywords, for example Should Match, support so called glob patterns where:
* |
matches any string, even an empty string |
? |
matches any single character |
[chars] |
matches one character in the bracket |
[!chars] |
matches one character not in the bracket |
[a-z] |
matches one character from the range in the bracket |
[!a-z] |
matches one character not from the range in the bracket |
Unlike with glob patterns normally, path separator characters /
and \
and the newline character \n
are matches by the above wildcards.
Support for brackets like [abc]
and [!a-z]
is new in Robot Framework 3.1.
Regular expressions
Some keywords, for example Should Match Regexp, support regular expressions that are more powerful but also more complicated that glob patterns. The regular expression support is implemented using Python's re module and its documentation should be consulted for more information about the syntax.
Because the backslash character (\
) is an escape character in Robot Framework test data, possible backslash characters in regular expressions need to be escaped with another backslash like \\d\\w+
. Strings that may contain special characters but should be handled as literal strings, can be escaped with the Regexp Escape keyword.
Multiline string comparison
Should Be Equal and Should Be Equal As Strings report the failures using unified diff format if both strings have more than two lines.
Example:
${first} = | Catenate | SEPARATOR=\n | Not in second | Same | Differs | Same |
${second} = | Catenate | SEPARATOR=\n | Same | Differs2 | Same | Not in first |
Should Be Equal | ${first} | ${second} |
Results in the following error message:
Multiline strings are different: --- first +++ second @@ -1,4 +1,4 @@ -Not in second Same -Differs +Differs2 Same +Not in first
String representations
Several keywords log values explicitly (e.g. Log) or implicitly (e.g. Should Be Equal when there are failures). By default keywords log values using "human readable" string representation, which means that strings like Hello
and numbers like 42
are logged as-is. Most of the time this is the desired behavior, but there are some problems as well:
- It is not possible to see difference between different objects that have same string representation like string
42
and integer42
. Should Be Equal and some other keywords add the type information to the error message in these cases, though.
- Non-printable characters such as the null byte are not visible.
- Trailing whitespace is not visible.
- Different newlines (
\r\n
on Windows,\n
elsewhere) cannot be separated from each others.
- There are several Unicode characters that are different but look the same. One example is the Latin
a
(\u0061
) and the Cyrillicа
(\u0430
). Error messages likea != а
are not very helpful.
- Some Unicode characters can be represented using different forms. For example,
ä
can be represented either as a single code point\u00e4
or using two code points\u0061
and\u0308
combined together. Such forms are considered canonically equivalent, but strings containing them are not considered equal when compared in Python. Error messages likeä != ä
are not that helpful either.
- Containers such as lists and dictionaries are formatted into a single line making it hard to see individual items they contain.
To overcome the above problems, some keywords such as Log and Should Be Equal have an optional formatter
argument that can be used to configure the string representation. The supported values are str
(default), repr
, and ascii
that work similarly as Python built-in functions with same names. More detailed semantics are explained below.
The formatter
argument is new in Robot Framework 3.1.2.
str
Use the "human readable" string representation. Equivalent to using str()
in Python 3 and unicode()
in Python 2. This is the default.
repr
Use the "machine readable" string representation. Similar to using repr()
in Python, which means that strings like Hello
are logged like 'Hello'
, newlines and non-printable characters are escaped like \n
and \x00
, and so on. Non-ASCII characters are shown as-is like ä
in Python 3 and in escaped format like \xe4
in Python 2. Use ascii
to always get the escaped format.
There are also some enhancements compared to the standard repr()
:
- Bigger lists, dictionaries and other containers are pretty-printed so that there is one item per row.
- On Python 2 the
u
prefix is omitted with Unicode strings and theb
prefix is added to byte strings.
ascii
Same as using ascii()
in Python 3 or repr()
in Python 2 where ascii()
does not exist. Similar to using repr
explained above but with the following differences:
- On Python 3 non-ASCII characters are escaped like
\xe4
instead of showing them as-is likeä
. This makes it easier to see differences between Unicode characters that look the same but are not equal. This is howrepr()
works in Python 2. - On Python 2 just uses the standard
repr()
meaning that Unicode strings get theu
prefix and nob
prefix is added to byte strings. - Containers are not pretty-printed.