BuiltIn.libspec

<?xml version="1.0" encoding="UTF-8"?>
<keywordspec name="BuiltIn" type="library" format="ROBOT" generated="20200529 10:52:03">
<version>3.1</version>
<scope>global</scope>
<namedargs>yes</namedargs>
<doc>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 comparisons`
- `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. These expressions are
evaluated using Python's
[http://docs.python.org/library/functions.html#eval|eval] function so
that all Python built-ins like ``len()`` and ``int()`` are available.
`Evaluate` allows configuring the execution namespace with custom modules,
and other keywords have [http://docs.python.org/library/os.html|os]
and [http://docs.python.org/library/sys.html|sys] modules available
automatically.

Examples:
| `Run Keyword If` | os.sep == '/' | Log                  | Not on Windows |
| ${random int} =  | `Evaluate`    | random.randint(0, 5) | modules=random |

When a variable is used in the expressing using the normal ``${variable}``
syntax, its value is replaces 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} &lt; 10                | Return code greater than 10 |
| `Run Keyword If` | '${status}' == 'PASS'     | Log | Passed                |
| `Run Keyword If` | 'FAIL' in '''${output}''' | Log | Output contains FAIL  |

Starting from Robot Framework 2.9, variables themselves are automatically
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, and in fact they are not even replaced
inside strings.

Examples:
| `Should Be True` | $rc &lt; 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) &gt; 1 and $result[1] == 'OK' |

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
regardless their value, and other argument types are tested using the same
[http://docs.python.org/library/stdtypes.html#truth|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
[http://en.wikipedia.org/wiki/Glob_(programming)|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
[http://en.wikipedia.org/wiki/Regular_expression|regular expressions]
that are more powerful but also more complicated that glob patterns.
The regular expression support is implemented using Python's
[http://docs.python.org/library/re.html|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 comparisons =

`Should Be Equal` and `Should Be Equal As Strings` report the failures using
[http://en.wikipedia.org/wiki/Diff_utility#Unified_format|unified diff
format] if both strings have more than two lines. New in Robot Framework
2.9.1.

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</doc>
<kw name="Call Method">
<arguments>
<arg>object</arg>
<arg>method_name</arg>
<arg>*args</arg>
<arg>**kwargs</arg>
</arguments>
<doc>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.

Support for ``**kwargs`` is new in Robot Framework 2.9. Since that
possible equal signs in other arguments must be escaped with a
backslash like ``\=``.

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      |         |         |
| Call Method      | ${object}    | kwargs    | name=value | foo=bar |
| Call Method      | ${object}    | positional   | escaped\=equals  |</doc>