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.

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 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 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 the b 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 how repr() works in Python 2.
  • On Python 2 just uses the standard repr() meaning that Unicode strings get the u prefix and no b prefix is added to byte strings.
  • Containers are not pretty-printed.