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
- Using variables with keywords creating or accessing variables
- Evaluating expressions
- Boolean arguments
- Pattern matching
- Multiline string comparison
- String representations
- 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.
Using variables with keywords creating or accessing variables
This library has special keywords Set Global Variable, Set Suite Variable, Set Test Variable and Set Local Variable for creating variables in different scopes. These keywords take the variable name and its value as arguments. The name can be given using the normal ${variable}
syntax or in escaped format either like $variable
or \${variable}
. For example, these are typically equivalent and create new suite level variable ${name}
with value value
:
Set Suite Variable ${name} value Set Suite Variable $name value Set Suite Variable \${name} value
A problem with using the normal ${variable}
syntax is that these keywords cannot easily know is the idea to create a variable with exactly that name or does that variable actually contain the name of the variable to create. If the variable does not initially exist, it will always be created. If it exists and its value is a variable name either in the normal or in the escaped syntax, variable with that name is created instead. For example, if ${name}
variable would exist and contain value $example
, these examples would create different variables:
Set Suite Variable ${name} value # Creates ${example}. Set Suite Variable $name value # Creates ${name}. Set Suite Variable \${name} value # Creates ${name}.
Because the behavior when using the normal ${variable}
syntax depends on the possible existing value of the variable, it is highly recommended to use the escaped $variable
or \${variable}
format instead.
This same problem occurs also with special keywords for accessing variables Get Variable Value, Variable Should Exist and Variable Should Not Exist.
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 ${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 in special cases where the automatic module import does not work such as when using nested modules like rootmod.submod
or list comprehensions. See the documentation of the Evaluate keyword for mode details.
Variables in expressions
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 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 # Stringfalse
is false. Should Be Equal ${x} ${y} Custom error values=no # Also stringno
is false. Should Be Equal ${x} ${y} Custom error values=${EMPTY} # Empty string is false. Should Be Equal ${x} ${y} Custom error values=${FALSE} # PythonFalse
is false. Should Be Equal ${x} ${y} Custom error values=no values #no values
works withvalues
argument
Pattern matching
Many keywords accept 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.
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 the 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 combined code points\u0061
and\u0308
. 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.
str
Use the human-readable string representation. Equivalent to using str()
in Python. 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 this mode bigger lists, dictionaries and other containers are pretty-printed so that there is one item per row.
ascii
Same as using ascii()
in Python. Similar to using repr
explained above but with the following differences:
- 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. - Containers are not pretty-printed.