robotide.lib.robot.libraries.BuiltIn.BuiltIn Class Reference

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

Inheritance diagram for robotide.lib.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 robotide.lib.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, item1, item2)
	Returns and logs how many times item2 is found from item1. 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')
	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, formatter='str')
	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)
	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, item1, item2, count, msg=None, ignore_case=False)
	Fails if item1 does not contain item2 count times. More...
def	should_end_with (self, str1, str2, msg=None, values=True, ignore_case=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)
	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)
	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)
	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)
	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)
	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)
	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)
	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)
	Fails if the string str1 does not start with the string str2. More...
Public Member Functions inherited from robotide.lib.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 robotide.lib.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_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 robotide.lib.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_if (self, condition, name, *args)
	Runs the given keyword with the given arguments, if condition is true. More...
def	run_keyword_if_all_critical_tests_passed (self, name, *args)
	Runs the given keyword with the given arguments, if all critical tests passed. 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_critical_tests_failed (self, name, *args)
	Runs the given keyword with the given arguments, if any critical tests failed. 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)
	Runs the given keyword with the given arguments if condition is false. 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 robotide.lib.robot.libraries.BuiltIn._Control
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	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...
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...
Public Member Functions inherited from robotide.lib.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 results. More...
def	get_library_instance (self, name=None, all=False)
	Returns the currently active instance of the specified test 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=False, 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)
	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 robotide.lib.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 ==

- `HTML error messages`
- `Evaluating expressions`
- `Boolean arguments`
- `Pattern matching`
- `Multiline string comparison`
- `String representations`
- `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} < 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 < 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' |

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

= 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 ``\u0061`` (``\\u0061``) and the Cyrillic
  ``\u0430`` (``\\u0430``). Error messages like ``\u0061 != \u0430`` are
  not very helpful.

- Some Unicode characters can be represented using
  [https://en.wikipedia.org/wiki/Unicode_equivalence|different forms].
  For example, ``\xe4`` 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 ``\xe4 != \u0061\u0308`` 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.

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

Definition at line 3551 of file BuiltIn.py.

Member Data Documentation

ROBOT_LIBRARY_SCOPE

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

static

Definition at line 3552 of file BuiltIn.py.

ROBOT_LIBRARY_VERSION

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

static

Definition at line 3553 of file BuiltIn.py.

---

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

• src/robotide/lib/robot/libraries/BuiltIn.py