|
Robot Framework
|
|
|
Robot Framework
|
|
Public Member Functions | |
| 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... | |
Private Member Functions | |
| def | _accepts_embedded_arguments (self, name) |
| def | _error_is_expected (self, error, expected_error) |
| def | _get_repeat_count (self, times, require_postfix=False) |
| def | _get_repeat_timeout (self, timestr) |
| def | _get_suite_in_teardown (self, kwname) |
| def | _get_test_in_teardown (self, kwname) |
| def | _keywords_repeated_by_count (self, count, name, args) |
| def | _keywords_repeated_by_timeout (self, timeout, name, args) |
| def | _replace_variables_in_name (self, name_and_args) |
| def | _run_keywords (self, iterable) |
| def | _split_branch (self, args, control_word, required, required_error) |
| def | _split_elif_or_else_branch (self, args) |
| def | _split_run_keywords (self, keywords) |
| def | _split_run_keywords_with_and (self, keywords) |
| def | _split_run_keywords_without_and (self, keywords) |
| def | _verify_values_for_set_variable_if (self, values, default=False) |
Additional Inherited Members | |
 Properties inherited from robot.libraries.BuiltIn._BuiltInBase | |
| _context = property | |
| _namespace = property | |
| _variables = property | |
Definition at line 1836 of file BuiltIn.py.
|
private |
Definition at line 1861 of file BuiltIn.py.
|
private |
Definition at line 2198 of file BuiltIn.py.
|
private |
Definition at line 2248 of file BuiltIn.py.
|
private |
Definition at line 2258 of file BuiltIn.py.
|
private |
Definition at line 2505 of file BuiltIn.py.
|
private |
Definition at line 2471 of file BuiltIn.py.
|
private |
Definition at line 2270 of file BuiltIn.py.
|
private |
Definition at line 2277 of file BuiltIn.py.
|
private |
Definition at line 1868 of file BuiltIn.py.
|
private |
Definition at line 1910 of file BuiltIn.py.
|
private |
Definition at line 2029 of file BuiltIn.py.
|
private |
Definition at line 2019 of file BuiltIn.py.
|
private |
Definition at line 1925 of file BuiltIn.py.
|
private |
Definition at line 1947 of file BuiltIn.py.
|
private |
Definition at line 1935 of file BuiltIn.py.
|
private |
Definition at line 2419 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.repeat_keyword | ( | self, | |
| repeat, | |||
| name, | |||
| * | args | ||
| ) |
Executes the specified keyword multiple times.
``name`` and ``args`` define the keyword that is executed similarly as
with `Run Keyword`. ``repeat`` specifies how many times (as a count) or
how long time (as a timeout) the keyword should be executed.
If ``repeat`` is given as count, it specifies how many times the
keyword should be executed. ``repeat`` can be given as an integer or
as a string that can be converted to an integer. If it is a string,
it can have postfix ``times`` or ``x`` (case and space insensitive)
to make the expression more explicit.
If ``repeat`` is given as timeout, it must be in Robot Framework's
time format (e.g. ``1 minute``, ``2 min 3 s``). Using a number alone
(e.g. ``1`` or ``1.5``) does not work in this context.
If ``repeat`` is zero or negative, the keyword is not executed at
all. This keyword fails immediately if any of the execution
rounds fails.
Examples:
| Repeat Keyword | 5 times | Go to Previous Page |
| Repeat Keyword | ${var} | Some Keyword | arg1 | arg2 |
| Repeat Keyword | 2 minutes | Some Keyword | arg1 | arg2 |
Definition at line 2236 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Executes the given keyword with the given arguments.
Because the name of the keyword to execute is given as an argument, it
can be a variable and thus set dynamically, e.g. from a return value of
another keyword or from the command line.
Definition at line 1851 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_and_continue_on_failure | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the keyword and continues execution even if a failure occurs.
The keyword name and arguments work as with `Run Keyword`.
Example:
| Run Keyword And Continue On Failure | Fail | This is a stupid example |
| Log | This keyword is executed |
The execution is not continued if the failure is caused by invalid syntax,
timeout, or fatal exception.
Definition at line 2126 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_and_expect_error | ( | self, | |
| expected_error, | |||
| name, | |||
| * | args | ||
| ) |
Runs the keyword and checks that the expected error occurred.
The keyword to execute and its arguments are specified using ``name``
and ``*args`` exactly like with `Run Keyword`.
The expected error must be given in the same format as in Robot Framework
reports. By default it is interpreted as a glob pattern with ``*``, ``?``
and ``[chars]`` as wildcards, but that can be changed by using various
prefixes explained in the table below. Prefixes are case-sensitive and
they must be separated from the actual message with a colon and an
optional space like ``PREFIX: Message`` or ``PREFIX:Message``.
| = Prefix = | = Explanation = |
| ``EQUALS`` | Exact match. Especially useful if the error contains glob wildcards. |
| ``STARTS`` | Error must start with the specified error. |
| ``REGEXP`` | Regular expression match. |
| ``GLOB`` | Same as the default behavior. |
See the `Pattern matching` section for more information about glob
patterns and regular expressions.
If the expected error occurs, the error message is returned and it can
be further processed or tested if needed. If there is no error, or the
error does not match the expected error, this keyword fails.
Examples:
| Run Keyword And Expect Error | My error | Keyword | arg |
| Run Keyword And Expect Error | ValueError: * | Some Keyword |
| Run Keyword And Expect Error | STARTS: ValueError: | Some Keyword |
| Run Keyword And Expect Error | EQUALS:No match for '//input[@type="text"]' |
| ... | Find Element | //input[@type="text"] |
| ${msg} = | Run Keyword And Expect Error | * |
| ... | Keyword | arg1 | arg2 |
| Log To Console | ${msg} |
Errors caused by invalid syntax, timeouts, or fatal exceptions are not
caught by this keyword.
*NOTE:* Regular expression matching used to require only the beginning
of the error to match the given pattern. That was changed in Robot
Framework 5.0 and nowadays the pattern must match the error fully.
To match only the beginning, add ``.*`` at the end of the pattern like
``REGEXP: Start.*``.
*NOTE:* Robot Framework 5.0 introduced native TRY/EXCEPT functionality
that is generally recommended for error handling. It supports same
pattern matching syntax as this keyword.
Definition at line 2183 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_and_ignore_error | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments and ignores possible error.
This keyword returns two values, so that the first is either string
``PASS`` or ``FAIL``, depending on the status of the executed keyword.
The second value is either the return value of the keyword or the
received error message. See `Run Keyword And Return Status` If you are
only interested in the execution status.
The keyword name and arguments work as in `Run Keyword`. See
`Run Keyword If` for a usage example.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not
caught by this keyword. Otherwise this keyword itself never fails.
*NOTE:* Robot Framework 5.0 introduced native TRY/EXCEPT functionality
that is generally recommended for error handling.
Definition at line 2066 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_and_return_status | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with given arguments and returns the status as a Boolean value.
This keyword returns Boolean ``True`` if the keyword that is executed
succeeds and ``False`` if it fails. This is useful, for example, in
combination with `Run Keyword If`. If you are interested in the error
message or return value, use `Run Keyword And Ignore Error` instead.
The keyword name and arguments work as in `Run Keyword`.
Example:
| ${passed} = | `Run Keyword And Return Status` | Keyword | args |
| `Run Keyword If` | ${passed} | Another keyword |
Errors caused by invalid syntax, timeouts, or fatal exceptions are not
caught by this keyword. Otherwise this keyword itself never fails.
Definition at line 2110 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_and_warn_on_failure | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the specified keyword logs a warning if the keyword fails.
This keyword is similar to `Run Keyword And Ignore Error` but if the executed
keyword fails, the error message is logged as a warning to make it more
visible. Returns status and possible return value or error message exactly
like `Run Keyword And Ignore Error` does.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not
caught by this keyword. Otherwise this keyword itself never fails.
New in Robot Framework 4.0.
Definition at line 2087 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if | ( | self, | |
| condition, | |||
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments, if condition is true.
*NOTE:* Robot Framework 4.0 introduced built-in IF/ELSE support and using
that is generally recommended over using this keyword.
The given ``condition`` is evaluated in Python as explained in the
`Evaluating expressions` section, and ``name`` and ``*args`` have same
semantics as with `Run Keyword`.
Example, a simple if/else construct:
| `Run Keyword If` | '${status}' == 'OK' | Some Action | arg |
| `Run Keyword If` | '${status}' != 'OK' | Another Action |
In this example, only either ``Some Action`` or ``Another Action`` is
executed, based on the value of the ``${status}`` variable.
Variables used like ``${variable}``, as in the examples above, are
replaced in the expression before evaluation. Variables are also
available in the evaluation namespace and can be accessed using special
``$variable`` syntax as explained in the `Evaluating expressions` section.
Example:
| `Run Keyword If` | $result is None or $result == 'FAIL' | Keyword |
This keyword supports also optional ELSE and ELSE IF branches. Both
of them are defined in ``*args`` and must use exactly format ``ELSE``
or ``ELSE IF``, respectively. ELSE branches must contain first the
name of the keyword to execute and then its possible arguments. ELSE
IF branches must first contain a condition, like the first argument
to this keyword, and then the keyword to execute and its possible
arguments. It is possible to have ELSE branch after ELSE IF and to
have multiple ELSE IF branches. Nested `Run Keyword If` usage is not
supported when using ELSE and/or ELSE IF branches.
Given previous example, if/else construct can also be created like this:
| `Run Keyword If` | '${status}' == 'PASS' | Some Action | arg | ELSE | Another Action |
The return value of this keyword is the return value of the actually
executed keyword or Python ``None`` if no keyword was executed (i.e.
if ``condition`` was false). Hence, it is recommended to use ELSE
and/or ELSE IF branches to conditionally assign return values from
keyword to variables (see `Set Variable If` you need to set fixed
values conditionally). This is illustrated by the example below:
| ${var1} = | `Run Keyword If` | ${rc} == 0 | Some keyword returning a value |
| ... | ELSE IF | 0 < ${rc} < 42 | Another keyword |
| ... | ELSE IF | ${rc} < 0 | Another keyword with args | ${rc} | arg2 |
| ... | ELSE | Final keyword to handle abnormal cases | ${rc} |
| ${var2} = | `Run Keyword If` | ${condition} | Some keyword |
In this example, ${var2} will be set to ``None`` if ${condition} is
false.
Notice that ``ELSE`` and ``ELSE IF`` control words must be used
explicitly and thus cannot come from variables. If you need to use
literal ``ELSE`` and ``ELSE IF`` strings as arguments, you can escape
them with a backslash like ``\\ELSE`` and ``\\ELSE IF``.
Definition at line 2013 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if_all_tests_passed | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments, if all tests passed.
This keyword can only be used in a suite teardown. Trying to use it
anywhere else results in an error.
Otherwise, this keyword works exactly like `Run Keyword`, see its
documentation for more details.
Definition at line 2486 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if_any_tests_failed | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments, if one or more tests failed.
This keyword can only be used in a suite teardown. Trying to use it
anywhere else results in an error.
Otherwise, this keyword works exactly like `Run Keyword`, see its
documentation for more details.
Definition at line 2500 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if_test_failed | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments, if the test failed.
This keyword can only be used in a test teardown. Trying to use it
anywhere else results in an error.
Otherwise, this keyword works exactly like `Run Keyword`, see its
documentation for more details.
Definition at line 2438 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if_test_passed | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword with the given arguments, if the test passed.
This keyword can only be used in a test teardown. Trying to use it
anywhere else results in an error.
Otherwise, this keyword works exactly like `Run Keyword`, see its
documentation for more details.
Definition at line 2452 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_if_timeout_occurred | ( | self, | |
| name, | |||
| * | args | ||
| ) |
Runs the given keyword if either a test or a keyword timeout has occurred.
This keyword can only be used in a test teardown. Trying to use it
anywhere else results in an error.
Otherwise, this keyword works exactly like `Run Keyword`, see its
documentation for more details.
Definition at line 2466 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keyword_unless | ( | self, | |
| condition, | |||
| name, | |||
| * | args | ||
| ) |
DEPRECATED since RF 5.0.
Use Native IF/ELSE or Run Keyword If instead.
Runs the given keyword with the given arguments if ``condition`` is false.
See `Run Keyword If` for more information and an example. Notice that this
keyword does not support ELSE or ELSE IF branches like `Run Keyword If` does.
Definition at line 2044 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.run_keywords | ( | self, | |
| * | keywords | ||
| ) |
Executes all the given keywords in a sequence.
This keyword is mainly useful in setups and teardowns when they need
to take care of multiple actions and creating a new higher level user
keyword would be an overkill.
By default all arguments are expected to be keywords to be executed.
Examples:
| `Run Keywords` | `Initialize database` | `Start servers` | `Clear logs` |
| `Run Keywords` | ${KW 1} | ${KW 2} |
| `Run Keywords` | @{KEYWORDS} |
Keywords can also be run with arguments using upper case ``AND`` as
a separator between keywords. The keywords are executed so that the
first argument is the first keyword and proceeding arguments until
the first ``AND`` are arguments to it. First argument after the first
``AND`` is the second keyword and proceeding arguments until the next
``AND`` are its arguments. And so on.
Examples:
| `Run Keywords` | `Initialize database` | db1 | AND | `Start servers` | server1 | server2 |
| `Run Keywords` | `Initialize database` | ${DB NAME} | AND | `Start servers` | @{SERVERS} | AND | `Clear logs` |
| `Run Keywords` | ${KW} | AND | @{KW WITH ARGS} |
Notice that the ``AND`` control argument must be used explicitly and
cannot itself come from a variable. If you need to use literal ``AND``
string as argument, you can either use variables or escape it with
a backslash like ``\\AND``.
Definition at line 1907 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.set_variable_if | ( | self, | |
| condition, | |||
| * | values | ||
| ) |
Sets variable based on the given condition.
The basic usage is giving a condition and two values. The
given condition is first evaluated the same way as with the
`Should Be True` keyword. If the condition is true, then the
first value is returned, and otherwise the second value is
returned. The second value can also be omitted, in which case
it has a default value None. This usage is illustrated in the
examples below, where ``${rc}`` is assumed to be zero.
| ${var1} = | Set Variable If | ${rc} == 0 | zero | nonzero |
| ${var2} = | Set Variable If | ${rc} > 0 | value1 | value2 |
| ${var3} = | Set Variable If | ${rc} > 0 | whatever | |
=>
| ${var1} = 'zero'
| ${var2} = 'value2'
| ${var3} = None
It is also possible to have 'else if' support by replacing the
second value with another condition, and having two new values
after it. If the first condition is not true, the second is
evaluated and one of the values after it is returned based on
its truth value. This can be continued by adding more
conditions without a limit.
| ${var} = | Set Variable If | ${rc} == 0 | zero |
| ... | ${rc} > 0 | greater than zero | less then zero |
| |
| ${var} = | Set Variable If |
| ... | ${rc} == 0 | zero |
| ... | ${rc} == 1 | one |
| ... | ${rc} == 2 | two |
| ... | ${rc} > 2 | greater than two |
| ... | ${rc} < 0 | less than zero |
Use `Get Variable Value` if you need to set variables
dynamically based on whether a variable exist or not.
Definition at line 2410 of file BuiltIn.py.
| def robot.libraries.BuiltIn._RunKeyword.wait_until_keyword_succeeds | ( | self, | |
| retry, | |||
| retry_interval, | |||
| name, | |||
| * | args | ||
| ) |
Runs the specified keyword and retries if it fails.
``name`` and ``args`` define the keyword that is executed similarly
as with `Run Keyword`. How long to retry running the keyword is
defined using ``retry`` argument either as timeout or count.
``retry_interval`` is the time to wait between execution attempts.
If ``retry`` is given as timeout, it must be in Robot Framework's
time format (e.g. ``1 minute``, ``2 min 3 s``, ``4.5``) that is
explained in an appendix of Robot Framework User Guide. If it is
given as count, it must have ``times`` or ``x`` postfix (e.g.
``5 times``, ``10 x``). ``retry_interval`` must always be given in
Robot Framework's time format.
By default ``retry_interval`` is the time to wait _after_ a keyword has
failed. For example, if the first run takes 2 seconds and the retry
interval is 3 seconds, the second run starts 5 seconds after the first
run started. If ``retry_interval`` start with prefix ``strict:``, the
execution time of the previous keyword is subtracted from the retry time.
With the earlier example the second run would thus start 3 seconds after
the first run started. A warning is logged if keyword execution time is
longer than a strict interval.
If the keyword does not succeed regardless of retries, this keyword
fails. If the executed keyword passes, its return value is returned.
Examples:
| Wait Until Keyword Succeeds | 2 min | 5 sec | My keyword | argument |
| ${result} = | Wait Until Keyword Succeeds | 3x | 200ms | My keyword |
| ${result} = | Wait Until Keyword Succeeds | 3x | strict: 200ms | My keyword |
All normal failures are caught by this keyword. Errors caused by
invalid syntax, test or keyword timeouts, or fatal exceptions (caused
e.g. by `Fatal Error`) are not caught.
Running the same keyword multiple times inside this keyword can create
lots of output and considerably increase the size of the generated
output files. It is possible to remove unnecessary keywords from
the outputs using ``--RemoveKeywords WUKS`` command line option.
Support for "strict" retry interval is new in Robot Framework 4.1.
Definition at line 2332 of file BuiltIn.py.
1.9.1