BuiltIn

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

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

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 integer 42. Should Be Equal and some other keywords add the type information to the error message in these cases, though.
  • Non-printable characters such as the null byte are not visible.
  • Trailing whitespace is not visible.
  • Different newlines (\r\n on Windows, \n elsewhere) cannot be separated from each others.
  • There are several Unicode characters that are different but look the same. One example is the Latin a (\u0061) and the Cyrillic а (\u0430). Error messages like a != а are not very helpful.
  • Some Unicode characters can be represented using 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.