robot.libraries.BuiltIn.BuiltIn Class Reference

An always available standard library with often needed keywords. More...

Inheritance diagram for robot.libraries.BuiltIn.BuiltIn:

Static Public Attributes
string	ROBOT_LIBRARY_SCOPE = 'GLOBAL'
	ROBOT_LIBRARY_VERSION = get_version()

Additional Inherited Members
Public Member Functions inherited from robot.libraries.BuiltIn._Verify
def	fail (self, msg=None, *tags)
	Fails the test with the given message and optionally alters its tags. More...
def	fatal_error (self, msg=None)
	Stops the whole test execution. More...
def	get_count (self, container, item)
	Returns and logs how many times item is found from container. More...
def	get_length (self, item)
	Returns and logs the length of the given item as an integer. More...
def	length_should_be (self, item, length, msg=None)
	Verifies that the length of the given item is correct. More...
def	should_be_empty (self, item, msg=None)
	Verifies that the given item is empty. More...
def	should_be_equal (self, first, second, msg=None, values=True, ignore_case=False, formatter='str', strip_spaces=False, collapse_spaces=False)
	Fails if the given objects are unequal. More...
def	should_be_equal_as_integers (self, first, second, msg=None, values=True, base=None)
	Fails if objects are unequal after converting them to integers. More...
def	should_be_equal_as_numbers (self, first, second, msg=None, values=True, precision=6)
	Fails if objects are unequal after converting them to real numbers. More...
def	should_be_equal_as_strings (self, first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, formatter='str', collapse_spaces=False)
	Fails if objects are unequal after converting them to strings. More...
def	should_be_true (self, condition, msg=None)
	Fails if the given condition is not true. More...
def	should_contain (self, container, item, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if container does not contain item one or more times. More...
def	should_contain_any (self, container, *items, **configuration)
	Fails if container does not contain any of the *items. More...
def	should_contain_x_times (self, container, item, count, msg=None, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if container does not contain item count times. More...
def	should_end_with (self, str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if the string str1 does not end with the string str2. More...
def	should_match (self, string, pattern, msg=None, values=True, ignore_case=False)
	Fails if the given string does not match the given pattern. More...
def	should_match_regexp (self, string, pattern, msg=None, values=True, flags=None)
	Fails if string does not match pattern as a regular expression. More...
def	should_not_be_empty (self, item, msg=None)
	Verifies that the given item is not empty. More...
def	should_not_be_equal (self, first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if the given objects are equal. More...
def	should_not_be_equal_as_integers (self, first, second, msg=None, values=True, base=None)
	Fails if objects are equal after converting them to integers. More...
def	should_not_be_equal_as_numbers (self, first, second, msg=None, values=True, precision=6)
	Fails if objects are equal after converting them to real numbers. More...
def	should_not_be_equal_as_strings (self, first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if objects are equal after converting them to strings. More...
def	should_not_be_true (self, condition, msg=None)
	Fails if the given condition is true. More...
def	should_not_contain (self, container, item, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if container contains item one or more times. More...
def	should_not_contain_any (self, container, *items, **configuration)
	Fails if container contains one or more of the *items. More...
def	should_not_end_with (self, str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if the string str1 ends with the string str2. More...
def	should_not_match (self, string, pattern, msg=None, values=True, ignore_case=False)
	Fails if the given string matches the given pattern. More...
def	should_not_match_regexp (self, string, pattern, msg=None, values=True, flags=None)
	Fails if string matches pattern as a regular expression. More...
def	should_not_start_with (self, str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if the string str1 starts with the string str2. More...
def	should_start_with (self, str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)
	Fails if the string str1 does not start with the string str2. More...
Public Member Functions inherited from robot.libraries.BuiltIn._Converter
def	convert_to_binary (self, item, base=None, prefix=None, length=None)
	Converts the given item to a binary string. More...
def	convert_to_boolean (self, item)
	Converts the given item to Boolean true or false. More...
def	convert_to_bytes (self, input, input_type='text')
	Converts the given input to bytes according to the input_type. More...
def	convert_to_hex (self, item, base=None, prefix=None, length=None, lowercase=False)
	Converts the given item to a hexadecimal string. More...
def	convert_to_integer (self, item, base=None)
	Converts the given item to an integer number. More...
def	convert_to_number (self, item, precision=None)
	Converts the given item to a floating point number. More...
def	convert_to_octal (self, item, base=None, prefix=None, length=None)
	Converts the given item to an octal string. More...
def	convert_to_string (self, item)
	Converts the given item to a Unicode string. More...
def	create_dictionary (self, *items)
	Creates and returns a dictionary based on the given items. More...
def	create_list (self, *items)
	Returns a list containing given items. More...
Public Member Functions inherited from robot.libraries.BuiltIn._Variables
def	get_variable_value (self, name, default=None)
	Returns variable value or default if the variable does not exist. More...
def	get_variables (self, no_decoration=False)
	Returns a dictionary containing all variables in the current scope. More...
def	log_variables (self, level='INFO')
	Logs all variables in the current scope with given log level. More...
def	replace_variables (self, text)
	Replaces variables in the given text with their current values. More...
def	set_global_variable (self, name, *values)
	Makes a variable available globally in all tests and suites. More...
def	set_local_variable (self, name, *values)
	Makes a variable available everywhere within the local scope. More...
def	set_suite_variable (self, name, *values)
	Makes a variable available everywhere within the scope of the current suite. More...
def	set_task_variable (self, name, *values)
	Makes a variable available everywhere within the scope of the current task. More...
def	set_test_variable (self, name, *values)
	Makes a variable available everywhere within the scope of the current test. More...
def	set_variable (self, *values)
	Returns the given values which can then be assigned to a variables. More...
def	variable_should_exist (self, name, msg=None)
	Fails unless the given variable exists within the current scope. More...
def	variable_should_not_exist (self, name, msg=None)
	Fails if the given variable exists within the current scope. More...
Public Member Functions inherited from robot.libraries.BuiltIn._RunKeyword
def	repeat_keyword (self, repeat, name, *args)
	Executes the specified keyword multiple times. More...
def	run_keyword (self, name, *args)
	Executes the given keyword with the given arguments. More...
def	run_keyword_and_continue_on_failure (self, name, *args)
	Runs the keyword and continues execution even if a failure occurs. More...
def	run_keyword_and_expect_error (self, expected_error, name, *args)
	Runs the keyword and checks that the expected error occurred. More...
def	run_keyword_and_ignore_error (self, name, *args)
	Runs the given keyword with the given arguments and ignores possible error. More...
def	run_keyword_and_return_status (self, name, *args)
	Runs the given keyword with given arguments and returns the status as a Boolean value. More...
def	run_keyword_and_warn_on_failure (self, name, *args)
	Runs the specified keyword logs a warning if the keyword fails. More...
def	run_keyword_if (self, condition, name, *args)
	Runs the given keyword with the given arguments, if condition is true. More...
def	run_keyword_if_all_tests_passed (self, name, *args)
	Runs the given keyword with the given arguments, if all tests passed. More...
def	run_keyword_if_any_tests_failed (self, name, *args)
	Runs the given keyword with the given arguments, if one or more tests failed. More...
def	run_keyword_if_test_failed (self, name, *args)
	Runs the given keyword with the given arguments, if the test failed. More...
def	run_keyword_if_test_passed (self, name, *args)
	Runs the given keyword with the given arguments, if the test passed. More...
def	run_keyword_if_timeout_occurred (self, name, *args)
	Runs the given keyword if either a test or a keyword timeout has occurred. More...
def	run_keyword_unless (self, condition, name, *args)
	DEPRECATED since RF 5.0. More...
def	run_keywords (self, *keywords)
	Executes all the given keywords in a sequence. More...
def	set_variable_if (self, condition, *values)
	Sets variable based on the given condition. More...
def	wait_until_keyword_succeeds (self, retry, retry_interval, name, *args)
	Runs the specified keyword and retries if it fails. More...
Public Member Functions inherited from robot.libraries.BuiltIn._Control
def	skip (self, msg='Skipped with Skip keyword.')
	Skips the rest of the current test. More...
def	skip_if (self, condition, msg=None)
	Skips the rest of the current test if the condition is True. More...
def	continue_for_loop (self)
	Skips the current FOR loop iteration and continues from the next. More...
def	continue_for_loop_if (self, condition)
	Skips the current FOR loop iteration if the condition is true. More...
def	exit_for_loop (self)
	Stops executing the enclosing FOR loop. More...
def	exit_for_loop_if (self, condition)
	Stops executing the enclosing FOR loop if the condition is true. More...
def	return_from_keyword (self, *return_values)
	Returns from the enclosing user keyword. More...
def	return_from_keyword_if (self, condition, *return_values)
	Returns from the enclosing user keyword if condition is true. More...
def	run_keyword_and_return (self, name, *args)
	Runs the specified keyword and returns from the enclosing user keyword. More...
def	run_keyword_and_return_if (self, condition, name, *args)
	Runs the specified keyword and returns from the enclosing user keyword. More...
def	pass_execution (self, message, *tags)
	Skips rest of the current test, setup, or teardown with PASS status. More...
def	pass_execution_if (self, condition, message, *tags)
	Conditionally skips rest of the current test, setup, or teardown with PASS status. More...
Public Member Functions inherited from robot.libraries.BuiltIn._Misc
def	call_method (self, object, method_name, *args, **kwargs)
	Calls the named method of the given object with the provided arguments. More...
def	catenate (self, *items)
	Catenates the given items together and returns the resulted string. More...
def	comment (self, *messages)
	Displays the given messages in the log file as keyword arguments. More...
def	evaluate (self, expression, modules=None, namespace=None)
	Evaluates the given expression in Python and returns the result. More...
def	get_library_instance (self, name=None, all=False)
	Returns the currently active instance of the specified library. More...
def	get_time (self, format='timestamp', time_='NOW')
	Returns the given time in the requested format. More...
def	import_library (self, name, *args)
	Imports a library with the given name and optional arguments. More...
def	import_resource (self, path)
	Imports a resource file with the given path. More...
def	import_variables (self, path, *args)
	Imports a variable file with the given path and optional arguments. More...
def	keyword_should_exist (self, name, msg=None)
	Fails unless the given keyword exists in the current scope. More...
def	log (self, message, level='INFO', html=False, console=False, repr='DEPRECATED', formatter='str')
	Logs the given message with the given level. More...
def	log_many (self, *messages)
	Logs the given messages as separate entries using the INFO level. More...
def	log_to_console (self, message, stream='STDOUT', no_newline=False, format='')
	Logs the given message to the console. More...
def	no_operation (self)
	Does absolutely nothing. More...
def	regexp_escape (self, *patterns)
	Returns each argument string escaped for use as a regular expression. More...
def	reload_library (self, name_or_instance)
	Rechecks what keywords the specified library provides. More...
def	remove_tags (self, *tags)
	Removes given tags from the current test or all tests in a suite. More...
def	set_library_search_order (self, *search_order)
	Sets the resolution order to use when a name matches multiple keywords. More...
def	set_log_level (self, level)
	Sets the log threshold to the specified level and returns the old level. More...
def	set_suite_documentation (self, doc, append=False, top=False)
	Sets documentation for the current test suite. More...
def	set_suite_metadata (self, name, value, append=False, top=False)
	Sets metadata for the current test suite. More...
def	set_tags (self, *tags)
	Adds given tags for the current test or all tests in a suite. More...
def	set_test_documentation (self, doc, append=False)
	Sets documentation for the current test case. More...
def	set_test_message (self, message, append=False)
	Sets message for the current test case. More...
def	sleep (self, time_, reason=None)
	Pauses the test executed for the given time. More...
Properties inherited from robot.libraries.BuiltIn._BuiltInBase
	_context = property
	_namespace = property
	_variables = property

Detailed Description

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

%TOC%

= 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
[http://docs.python.org/library/functions.html#eval|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
[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

= Pattern matching =

Many keywords accept 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.

== 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 comparison =

`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.

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
  [https://en.wikipedia.org/wiki/Unicode_equivalence|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
[https://docs.python.org/library/functions.html|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.

Definition at line 3944 of file BuiltIn.py.

Member Data Documentation

ROBOT_LIBRARY_SCOPE

string robot.libraries.BuiltIn.BuiltIn.ROBOT_LIBRARY_SCOPE = 'GLOBAL'

static

Definition at line 3945 of file BuiltIn.py.

ROBOT_LIBRARY_VERSION

robot.libraries.BuiltIn.BuiltIn.ROBOT_LIBRARY_VERSION = get_version()

static

Definition at line 3946 of file BuiltIn.py.

---

The documentation for this class was generated from the following file:

• src/robot/libraries/BuiltIn.py