Source code for robot.libraries.BuiltIn

#  Copyright 2008-2015 Nokia Networks
#  Copyright 2016-     Robot Framework Foundation
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

import difflib
import re
import time
from collections.abc import Collection, Mapping, Sequence, Sized
from datetime import datetime, timedelta
from typing import Any, Callable, Iterator, Literal, NoReturn

from robot.api import logger, SkipExecution
from robot.api.deco import library
from robot.api.types import KeywordArgument, KeywordName
from robot.errors import (
    BreakLoop, ContinueLoop, DataError, ExecutionFailed, ExecutionFailures,
    ExecutionPassed, PassExecution, ReturnFromKeyword, VariableError
)
from robot.output import SettableLevel
from robot.running import Keyword, RUN_KW_REGISTER, TypeInfo
from robot.running.context import EXECUTION_CONTEXTS
from robot.utils import (
    DotDict, escape, format_assign_message, get_error_message, get_time, html_escape,
    is_truthy, Matcher, normalize, normalize_whitespace, NormalizedDict, parse_re_flags,
    parse_time, plural_or_not as s, prepr, safe_str, secs_to_timestr, seq2str,
    split_from_equals, timestr_to_secs, type_name, unescape
)
from robot.utils.asserts import assert_equal, assert_not_equal
from robot.variables import (
    DictVariableResolver, evaluate_expression, is_dict_variable, is_list_variable,
    search_variable, VariableResolver
)
from robot.version import get_version

from .normalizer import Normalizer, StripSpaces


[docs] class Expression: """An expression evaluated in Python. Expressions are evaluated using Python's [eval](https://docs.python.org/library/functions.html#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: ```robotframework *** Test Cases *** Evaluating expressions Should Be True len("${result}") > 3 Run Keyword If os.sep == "/" Non-Windows Keyword ${version} = Evaluate robot.__version__ ``` 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: ```robotframework *** Test Cases *** Using normal variables Should Be True ${rc} < 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: ```robotframework *** Test Cases *** Special variable syntax Should Be True $rc < 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 ``` """
[docs] def run_keyword_variant(resolve, dry_run=False): def decorator(method): RUN_KW_REGISTER.register_run_keyword( "BuiltIn", method.__name__, resolve, deprecation_warning=False, dry_run=dry_run, ) return method return decorator
class _BuiltInBase: @property def robot_running(self) -> bool: """Return True/False depending on is Robot Framework running or not. Can be used by libraries and other extensions. New in Robot Framework 6.1. """ return EXECUTION_CONTEXTS.current is not None @property def dry_run_active(self) -> bool: """Return True/False depending on is dry-run active or not. Can be used by libraries and other extensions. Notice that library keywords are not run at all in dry-run, but library `__init__` can utilize this information. New in Robot Framework 6.1. """ return self.robot_running and self._context.dry_run @property def _context(self): return self._get_context() def _get_context(self, top=False): ctx = EXECUTION_CONTEXTS.current if not top else EXECUTION_CONTEXTS.top if ctx is None: raise RobotNotRunningError("Cannot access execution context") return ctx @property def _namespace(self): return self._get_context().namespace @property def _variables(self): return self._namespace.variables def _matches(self, string: str, pattern: str, caseless: bool = False) -> bool: # Must use this instead of fnmatch when string may contain newlines. matcher = Matcher(pattern, caseless=caseless, spaceless=False) return matcher.match(string) def _is_true(self, condition: Expression) -> bool: if isinstance(condition, str): condition = self.evaluate(condition) return bool(condition) def _log_types(self, *args: object): self._log_types_at_level("DEBUG", *args) def _log_types_at_level(self, level: logger.LogLevel, *args: object): msg = ["Argument types are:"] + [str(type(a)) for a in args] logger.write("\n".join(msg), level) def _convert_to_integer(self, item: object, base: "int | None" = None) -> int: orig = item if isinstance(item, str): item = normalize(item, ignore="_") if not base: item, base = self._get_base(item) try: if not base: return int(item) if not isinstance(item, (str, bytes, bytearray)): raise ValueError(f"{type_name(item)} objects do not support base.") return int(item, base) except Exception as err: raise ValueError(f"'{orig}' cannot be converted to an integer: {err}") def _get_base(self, value: str) -> "tuple[str, int | None]": if value.startswith(("-", "+")): sign = value[0] value = value[1:] else: sign = "" bases = {"0b": 2, "0o": 8, "0x": 16} if value.startswith(tuple(bases)): return sign + value[2:], bases[value[:2]] return sign + value, None def _convert_to_number(self, item: object, precision: "int | None" = None) -> float: if isinstance(item, str): item = normalize(item, ignore="_") number = self._convert_to_number_without_precision(item) if precision is not None: number = float(round(number, precision)) return number def _convert_to_number_without_precision(self, item: object) -> float: try: return float(item) # type: ignore except Exception as err: try: return float(self._convert_to_integer(item)) except ValueError: raise ValueError( f"'{item}' cannot be converted to a floating point number: {err}" ) def _get_formatter(self, name: str) -> Callable[[object], object]: formatters = { "str": safe_str, "repr": prepr, "ascii": ascii, "len": len, "type": lambda x: type(x).__name__, } try: return formatters[name.lower()] except KeyError: raise ValueError( f"Invalid formatter '{name}'. Available {seq2str(formatters)}." ) class _Converter(_BuiltInBase): def convert_to_integer(self, item: object, base: "int | None" = None) -> int: """Converts the given item to an integer number. Args: item: The value to convert. base: The optional integer base. Returns: The converted integer. If the given item is a string, it is, by default, expected to be an integer in base 10. There are two ways to convert from other bases: - Give the base explicitly using the `base` argument. - Prefix the given string with the base so that `0b` means binary (base 2), `0o` means octal (base 8), and `0x` means hex (base 16). The prefix is considered only when the `base` argument is not used. The syntax is case-insensitive and possible spaces and underscores are ignored. Examples: ```robotframework *** Test Cases *** Convert to integer ${result} = Convert To Integer 100 # 100 ${result} = Convert To Integer FF AA 16 # 65450 ${result} = Convert To Integer 100 8 # 64 ${result} = Convert To Integer -100 2 # -4 ${result} = Convert To Integer 0b100 # 4 ${result} = Convert To Integer -0x100 # -256 ``` See also [Convert To Number], [Convert To Binary], [Convert To Octal], [Convert To Hex], and [Convert To Bytes]. """ self._log_types(item) return self._convert_to_integer(item, base) def convert_to_binary( self, item: object, base: "int | None" = None, prefix: "str | None" = None, length: "int | None" = None, ) -> str: """Converts the given item to a binary string. Args: item: The value to convert. base: The optional base used in integer conversion. prefix: The optional prefix added to the converted number. length: The minimum length of the converted number without the possible prefix or the minus sign. Returns: The converted binary string. The `item`, with the optional `base`, is first converted to an integer using the [Convert To Integer] keyword internally. After that it is converted to a binary number (base 2) represented as a string like `1101`. The converted number can be given a custom prefix such as `0b` by using the `prefix` argument. If the number is negative, the prefix is added after the minus sigh like `-0b1101`. The `length` argument can be used to specify the minimum length of the converted number. If the value is initially shorter, it is padded with zeros. For example, a number with minimum length of eight could look like `00001101`. Calculating the length does not take the possible prefix or the minus sigh into account. Examples: ```robotframework *** Test Cases *** Convert to binary ${bin} = Convert To Binary 10 # 1010 ${bin} = Convert To Binary D base=16 prefix=0b # 0b1101 ${bin} = Convert To Binary -2 prefix=% length=4 # -%0010 ``` See also [Convert To Integer], [Convert To Octal] and [Convert To Hex]. """ return self._convert_to_bin_oct_hex(item, base, prefix, length, "b") def convert_to_octal( self, item: object, base: "int | None" = None, prefix: "str | None" = None, length: "int | None" = None, ) -> str: """Converts the given item to an octal string. Args: item: The value to convert. base: The optional base used in integer conversion. prefix: The optional prefix added to the converted number. length: The minimum length of the converted number without the possible prefix or the minus sign. Returns: The converted octal string. The `item`, with an optional `base`, is first converted to an integer using the [Convert To Integer] keyword internally. After that it is converted to an octal number (base 8) represented as a string like `775`. The converted number can be given a custom prefix such as `0o` by using the `prefix` argument. If the number is negative, the prefix is added after the minus sigh like `-0o775`. The `length` argument can be used to specify the minimum length of the converted number. If the value is initially shorter, it is padded with zeros. For example, a number with minimum length of eight could look like `00000755`. Calculating the length does not take the possible prefix or the minus sigh into account. Examples: ```robotframework *** Test Cases *** Convert to octal ${oct} = Convert To Octal 10 # 12 ${oct} = Convert To Octal -F base=16 prefix=0 # -017 ${oct} = Convert To Octal 16 prefix=0o length=4 # 0o0020 ``` See also [Convert To Integer], [Convert To Binary] and [Convert To Hex]. """ return self._convert_to_bin_oct_hex(item, base, prefix, length, "o") def convert_to_hex( self, item: object, base: "int | None" = None, prefix: "str | None" = None, length: "int | None" = None, lowercase: bool = False, ) -> str: """Converts the given item to a hexadecimal string. Args: item: The value to convert. base: The optional base used in integer conversion. prefix: The optional prefix added to the converted number. length: The minimum length of the converted number without the possible prefix or the minus sign. lowercase: If true, the number is returned in lower case. Returns: The converted hexadecimal string. The `item`, with an optional `base`, is first converted to an integer using the [Convert To Integer] keyword internally. After that it is converted to a hexadecimal number (base 16) represented as a string like `FF0A`. The converted number can be given a custom prefix such as `0x` by using the `prefix` argument. If the number is negative, the prefix is added after the minus sigh like `-0xFF0A`. The `length` argument can be used to specify the minimum length of the converted number. If the value is initially shorter, it is padded with zeros. For example, a number with minimum length of eight could look like `0000FF0A`. Calculating the length does not take the possible prefix or the minus sigh into account. The number uses upper case characters by default, but that can be changed by giving the `lowercase` argument a true value. This option does not affect the optional `prefix`. Examples: ```robotframework *** Test Cases *** Convert to hex ${hex} = Convert To Hex 255 # FF ${hex} = Convert To Hex -10 prefix=0x length=2 # -0x0A ${hex} = Convert To Hex 255 prefix=$ lowercase=True # $ff ``` See also [Convert To Integer], [Convert To Binary] and [Convert To Octal]. """ spec = "x" if lowercase else "X" return self._convert_to_bin_oct_hex(item, base, prefix, length, spec) def _convert_to_bin_oct_hex( self, item: object, base: "int | None", prefix: "str | None", length: "int | None", format_spec: str, ) -> str: self._log_types(item) ret = format(self._convert_to_integer(item, base), format_spec) prefix = prefix or "" if ret[0] == "-": prefix = "-" + prefix ret = ret[1:] if length: ret = ret.rjust(length, "0") return prefix + ret def convert_to_number(self, item: object, precision: "int | None" = None) -> float: """Converts the given item to a floating point number. Args: item: The value to convert. precision: If given, the number is rounded to this precision. Returns: The converted floating point number. If the optional `precision` is positive or zero, the returned number is rounded to that number of decimal digits. Negative precision means that the number is rounded to the closest multiple of 10 to the power of the absolute precision. If a number is equally close to a certain precision, it is rounded toward the even choice. In addition to floating point values, all values accepted by [Convert To Integer] can be used as well. The syntax is case-insensitive and possible spaces and underscores are ignored. Examples: ```robotframework *** Test Cases *** Convert to number ${num} = Convert To Number 42.512 # 42.512 ${num} = Convert To Number 42.512 1 # 42.5 ${num} = Convert To Number 42.512 0 # 43.0 ${num} = Convert To Number 42.512 -1 # 40.0 ${num} = Convert To Number 1E10 # 10000000000 ``` Notice that machines generally cannot store floating point numbers accurately. This may cause surprises with these numbers in general and also when they are rounded. For more information see, for example, these resources: - https://docs.python.org/tutorial/floatingpoint.html - https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/ If you want to avoid possible problems with floating point numbers, you can implement custom keywords using Python's [decimal](http://docs.python.org/library/decimal.html) or [fractions](http://docs.python.org/library/fractions.html) modules. If you need an integer number, use [Convert To Integer] instead. """ self._log_types(item) return self._convert_to_number(item, precision) def convert_to_string(self, item: object) -> str: """Converts the given item to a Unicode string. Args: item: The value to convert Returns: The converted string. Strings are also [NFC normalized][NFC]. Use `Encode String To Bytes` and `Decode Bytes To String` keywords in the String library if you need to convert between Unicode and byte strings using different encodings. Use [Convert To Bytes] if you want to create byte strings. """ self._log_types(item) return safe_str(item) def convert_to_boolean(self, item: object) -> bool: """Converts the given item to Boolean `True` or `False`. Args: item: The value to convert. Returns: Boolean `True` or `False`. Returns item's [truth value](http://docs.python.org/library/stdtypes.html#truth). Uses Python's `bool()` function in other cases, but the string `FALSE`, case-insensitively, is considered `False`. Notice that this keyword handles strings differently than argument and variable conversion where also strings like `OFF` and `0` are considered `False`. """ self._log_types(item) if isinstance(item, str) and item.title() == "False": return False return bool(item) def convert_to_bytes( self, input: object, input_type: Literal["text", "int", "hex", "bin"] = "text", ) -> bytes: r"""Converts the given `input` to bytes according to the `input_type`. Args: input: The value to convert. input_type: The type of the input. Returns: The converted byte string. Valid input types are: - `text`: Converts text to bytes character by character. All characters with ordinal below 256 can be used and are converted to bytes with same values. Many characters are easiest to represent using escapes like `\x00` or `\xff`. In practice this is the same as Latin-1 encoding. - `int`: Converts integers separated by spaces to bytes. Similarly as with [Convert To Integer], it is possible to use binary, octal, or hex values by prefixing the values with `0b`, `0o`, or `0x`, respectively. - `hex`: Converts hexadecimal values to bytes. Single byte is always two characters long (e.g. `01` or `FF`). Spaces are ignored and can be used freely as visual separators. - `bin`: Converts binary values to bytes. Single byte is always eight characters long (e.g. `00001010`). Spaces are ignored and can be used freely as visual separators. In addition to giving the input as a string, it is possible to use lists or other iterables containing individual characters or numbers. In that case numbers do not need to be padded to certain length, and they cannot contain extra spaces. Examples: ```robotframework *** Test Cases *** Convert to bytes ${bytes} = Convert To Bytes hyvä # hyv\xe4 ${bytes} = Convert To Bytes hyv\xe4 # hyv\xe4 ${bytes} = Convert To Bytes \xff\x07 # \xff\x07 ${bytes} = Convert To Bytes 82 70 int # RF ${bytes} = Convert To Bytes 0b10 0x10 int # \x02\x10 ${bytes} = Convert To Bytes ff 00 07 hex # \xff\x00\x07 ${bytes} = Convert To Bytes 52462121 hex # RF!! ${bytes} = Convert To Bytes 0000 1000 bin # \x08 ${input} = Create List 1 2 12 ${bytes} = Convert To Bytes ${input} int # \x01\x02\x0c ${bytes} = Convert To Bytes ${input} hex # \x01\x02\x12 ``` Use `Encode String To Bytes` in the String library if you need to convert text to bytes using a certain encoding. """ try: try: get_ordinals = getattr(self, f"_get_ordinals_from_{input_type}") except AttributeError: raise RuntimeError(f"Invalid input type '{input_type}'.") return bytes(o for o in get_ordinals(input)) except Exception: raise RuntimeError("Creating bytes failed: " + get_error_message()) def _get_ordinals_from_text(self, input: Any) -> Iterator[int]: for char in input: ordinal = char if isinstance(char, int) else ord(char) yield self._test_ordinal(ordinal, char, "Character") def _test_ordinal(self, ordinal: int, original: object, type: str) -> int: if 0 <= ordinal <= 255: return ordinal raise RuntimeError(f"{type} '{original}' cannot be represented as a byte.") def _get_ordinals_from_int(self, input: Any) -> Iterator[int]: if isinstance(input, str): input = input.split() elif isinstance(input, int): input = [input] for integer in input: ordinal = self._convert_to_integer(integer) yield self._test_ordinal(ordinal, integer, "Integer") def _get_ordinals_from_hex(self, input: Any) -> Iterator[int]: for token in self._input_to_tokens(input, length=2): ordinal = self._convert_to_integer(token, base=16) yield self._test_ordinal(ordinal, token, "Hex value") def _get_ordinals_from_bin(self, input: Any) -> Iterator[int]: for token in self._input_to_tokens(input, length=8): ordinal = self._convert_to_integer(token, base=2) yield self._test_ordinal(ordinal, token, "Binary value") def _input_to_tokens(self, input: Any, length: int) -> Sequence: if not isinstance(input, str): return input input = "".join(input.split()) if len(input) % length != 0: raise RuntimeError(f"Expected input to be multiple of {length}.") return [input[i : i + length] for i in range(0, len(input), length)] def create_list(self, *items: object) -> list: """Creates and returns a list containing the given items. Args: items: The items to add to the list. Returns: The created list containing the given items. Examples: ```robotframework *** Test Cases *** Create list @{chars} = Create List a b c @{ints} = Create List ${1} ${2} ${3} ``` """ return list(items) @run_keyword_variant(resolve=0) def create_dictionary(self, *items: object) -> DotDict: """Creates and returns a dictionary based on the given `items`. Args: items: The items to add to the dictionary. Returns: The created dictionary containing the given items. Items are typically given using the `key=value` syntax same way as `&{dictionary}` variables are created in the Variable section. Both keys and values can contain variables, and possible equal sign in key can be escaped with a backslash like `escaped\\=key=value`. It is also possible to get items from existing dictionaries by simply using them like `&{dict}`. Alternatively items can be specified so that keys and values are given separately. This and the `key=value` syntax can even be combined, but separately given items must be first. If same key is used multiple times, the last value has precedence. The returned dictionary is ordered, and values with strings as keys can also be accessed using a convenient dot-access syntax like `${dict.key}`. Technically the returned dictionary is Robot Framework's own `DotDict` instance. If there is a need, it can be converted into a regular Python `dict` instance by using the `Convert To Dictionary` keyword from the Collections library. Examples: ```robotframework *** Variables *** &{DICT} key=value foo=bar *** Test Cases *** `key=value` syntax &{result} = Create Dictionary key=value foo=bar Should Be Equal ${result} ${DICT} Key and value separately &{result} = Create Dictionary key value foo bar Should Be Equal ${result} ${DICT} Using variables &{result} = Create Dictionary &{DICT} foo=new ${1}=${2} Should Be Equal ${result} {"key": "value", "foo": "new", 1: 2} type=dict Should Be Equal ${result.key} value # dot-access Should Be Equal ${result}[foo] new # normal item access Should Be Equal ${result}[${1}] ${2} ``` """ separate, combined = self._split_dict_items(items) result = DotDict(self._format_separate_dict_items(separate)) combined = DictVariableResolver(combined).resolve(self._variables) result.update(combined) return result def _split_dict_items(self, items): separate = [] for item in items: _, value = split_from_equals(item) if value is not None or is_dict_variable(item): break separate.append(item) return separate, items[len(separate) :] def _format_separate_dict_items(self, separate): separate = self._variables.replace_list(separate) if len(separate) % 2 != 0: raise DataError( f"Expected even number of keys and values, got {len(separate)}." ) return [separate[i : i + 2] for i in range(0, len(separate), 2)] class _Verify(_BuiltInBase): def _set_and_remove_tags(self, tags: "Sequence[str]"): set_tags = [tag for tag in tags if not tag.startswith("-")] remove_tags = [tag[1:] for tag in tags if tag.startswith("-")] if remove_tags: self.remove_tags(*remove_tags) if set_tags: self.set_tags(*set_tags) def fail(self, msg: "str | None" = None, *tags: str) -> NoReturn: """Fails the test or task with the given message and optionally alters its tags. Args: msg: The error message to use. tags: Tags to set or remove. Tags starting with `-` are removed. The error message is specified using the `msg` argument. It is possible to use HTML in the given error message, similarly as with any other keyword accepting an error message, by prefixing the error with `*HTML*`. It is possible to modify tags of the current test or task by passing tags after the message. Tags starting with a hyphen (e.g. `-regression`) are removed and others added. Tags are modified using [Set Tags] and [Remove Tags] internally, and the semantics setting and removing them are the same as with these keywords. Examples: ```robotframework *** Test Cases *** Fails with the given message Fail Test not ready HTML message Fail *HTML* <b>Test not ready</b> Add tag Fail Test not ready not-ready Remove tag Fail OS not supported -regression ``` Use the [Fatal Error] keyword if you need to stop the whole execution. """ self._set_and_remove_tags(tags) raise AssertionError(msg) if msg is not None else AssertionError() def fatal_error(self, msg: "str | None" = None) -> NoReturn: """Stops the whole execution. Args: msg: The error message to use. The test, task or suite where this keyword is used fails with the provided message, and subsequent tests or tasks fail with a canned message. Possible teardowns will nevertheless be executed. Use the [Fail] keyword if you only want to stop one test or task. """ error = AssertionError(msg) if msg else AssertionError() error.ROBOT_EXIT_ON_FAILURE = True raise error def should_not_be_true(self, condition: Expression, msg: "str | None" = None): """Fails if the given condition is true. Args: condition: The condition to evaluate. msg: The custom error message. See [Should Be True] for details about how `condition` is evaluated and how `msg` can be used to override the default error message. """ if self._is_true(condition): raise AssertionError(msg or f"'{condition}' should not be true.") def should_be_true(self, condition: Expression, msg: "str | None" = None): """Fails if the given condition is not true. Args: condition: The condition to evaluate. msg: The custom error message. If `condition` is a string (e.g. `${rc} < 10`), it is evaluated as a Python expression as explained in the [Evaluating expressions] section and the keyword status is decided based on the result. If a non-string value is given, the status is got directly from its [truth value](http://docs.python.org/library/stdtypes.html#truth). The default error message (`<condition> should be true`) is not very informative, but it can be overridden with the `msg` argument. Examples: ```robotframework *** Test Cases *** Should be true Should Be True ${rc} < 10 Should Be True "${status}" == "PASS" # Strings must be quoted Should Be True ${number} # Passes if ${number} is not zero Should Be True ${list} # Passes if ${list} is not empty ``` 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 the special `$variable` syntax as explained in the [Evaluating expressions] section. Examples: ```robotframework *** Test Cases *** Special variable syntax Should Be True $rc < 10 Should Be True $status == "PASS" # Expected string must be quoted ``` """ if not self._is_true(condition): raise AssertionError(msg or f"'{condition}' should be true.") def should_be_equal( self, first: object, second: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, formatter: Literal["str", "repr", "ascii"] = "str", strip_spaces: StripSpaces = False, collapse_spaces: bool = False, type: "Literal['AUTO'] | Any | None" = None, types: "Any | None" = None, # TODO: 'Any' -> 'TypeForm' with 'type' and 'types' once PEP 747 lands. ): r"""Fails if the given objects are unequal. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. formatter: The formatter to use with values shown in the error message. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. type: Used for automatic type validation and conversion. types: Used for automatic type conversion. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String representations] section explains how `formatter` can be used for formatting values shown in failure messages. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. The `type` and `types` arguments control optional type conversion: - If `type` is used, the argument `first` is validated to match that type. In addition to that, the argument `second` is converted to that type before comparing values for equality. - If `types` is used, both `first` and `second` are converted without type validation. - Supported types are the same as supported by the [automatic argument conversion][1] such as `int`, `bytes` and `list`. Also parameterized types like `list[int]` and unions like `int | float` are supported. - When using `type`, a special value `AUTO` (case-insensitive) can be used to convert the `second` to the same type that the `first` has. - Using both `type` and `types` at the same time is an error. If explicit type information is not given and the first argument is bytes, the second argument is automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should be equal Should Be Equal ${x} expected Should Be Equal ${x} expected Custom error message Should Be Equal ${x} expected Custom message values=False Should Be Equal ${x} expected ignore_case=True formatter=repr Should Be Equal ${x} [1, 2] type=list Should Be Equal ${x} ${y} types=int | float ``` `type` and `types` are new in Robot Framework 7.2. Automatic bytes conversion, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. [1]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#supported-conversions """ self._log_types_at_info_if_different(first, second) if type or types: first, second = self._type_convert(first, second, type, types) elif isinstance(first, (bytes, bytearray)): second = self._ensure_bytes(second) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: first = normalizer.normalize(first) second = normalizer.normalize(second) self._should_be_equal(first, second, msg, values, formatter) def _type_convert( self, first: object, second: object, type: Any, types: Any, type_builtin=type, ) -> "tuple[object, object]": if type and types: raise TypeError("Cannot use both 'type' and 'types' arguments.") if types: type = types elif isinstance(type, str) and type.upper() == "AUTO": type = type_builtin(first) converter = TypeInfo.from_type_hint(type).get_converter() if types: first = converter.convert(first, "first") elif not converter.no_conversion_needed(first): raise ValueError( f"Argument 'first' got value {first!r} that does not " f"match type {type!r}." ) return first, converter.convert(second, "second") def _ensure_bytes(self, value: object) -> "bytes | bytearray": if isinstance(value, (bytes, bytearray)): return value return TypeInfo.from_type(bytes).convert(value) # type: ignore def _should_be_equal( self, first: object, second: object, msg: "str | None", values: bool, formatter: Literal["str", "repr", "ascii"] = "str", ): include_values = self._deprecate_no_values(values) formatter = self._get_formatter(formatter) if first == second: return if include_values and isinstance(first, str) and isinstance(second, str): self._raise_multi_diff(first, second, msg, formatter) assert_equal(first, second, msg, include_values, formatter) def _log_types_at_info_if_different(self, first: object, second: object): level: logger.LogLevel = "DEBUG" if type(first) is type(second) else "INFO" self._log_types_at_level(level, first, second) def _raise_multi_diff( self, first: str, second: str, msg: "str | None", formatter: Callable, ): first_lines = first.splitlines(keepends=True) second_lines = second.splitlines(keepends=True) if len(first_lines) < 3 or len(second_lines) < 3: return logger.info(f"{first.rstrip()}\n\n!=\n\n{second.rstrip()}") diffs = list( difflib.unified_diff( first_lines, second_lines, fromfile="first", tofile="second", lineterm="", ) ) diffs[3:] = [item[0] + formatter(item[1:]).rstrip() for item in diffs[3:]] prefix = "Multiline strings are different:" if msg: prefix = f"{msg}: {prefix}" raise AssertionError("\n".join([prefix, *diffs])) def _deprecate_no_values(self, values: "bool | str") -> bool: # Deprecated in RF 7.4. TODO: Remove in RF 9. if isinstance(values, str) and values.upper() == "NO VALUES": logger.warn( f"Using '{values}' for disabling the 'values' argument is deprecated. " f"Use 'values=False' instead." ) return False return bool(values) def should_not_be_equal( self, first: object, second: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the given objects are equal. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If the first argument is bytes, the second argument is automatically converted to bytes as well. Automatic bytes conversion, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. """ self._log_types_at_info_if_different(first, second) if isinstance(first, (bytes, bytearray)): second = self._ensure_bytes(second) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: first = normalizer.normalize(first) second = normalizer.normalize(second) self._should_not_be_equal(first, second, msg, values) def _should_not_be_equal( self, first: object, second: object, msg: "str | None", values: bool, ): assert_not_equal(first, second, msg, self._deprecate_no_values(values)) def should_not_be_equal_as_integers( self, first: object, second: object, msg: "str | None" = None, values: bool = True, base: "int | None" = None, ): """Fails if objects are equal after converting them to integers. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. base: The optional base to use in integer conversion. See [Convert To Integer] for information how to convert integers from other bases than 10 by using the `base` argument and `0b/0o/0x` prefixes. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. See [Should Be Equal As Integers] for some usage examples. """ self._log_types_at_info_if_different(first, second) first = self._convert_to_integer(first, base) second = self._convert_to_integer(second, base) self._should_not_be_equal(first, second, msg, values) def should_be_equal_as_integers( self, first: object, second: object, msg: "str | None" = None, values: bool = True, base: "int | None" = None, ): """Fails if objects are unequal after converting them to integers. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. base: Optional base to use in integer conversion. See [Convert To Integer] for information how to convert integers from other bases than 10 by using the `base` argument and `0b/0o/0x` prefixes. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. Examples: ```robotframework *** Test Cases *** Should be equal as integers Should Be Equal As Integers 42 ${42} Error message Should Be Equal As Integers ABCD abcd base=16 Should Be Equal As Integers 0b1011 11 ``` An alternative to using [Should Be Equal As Integers] is using the [Should Be Equal] keyword with `type` and `types` arguments that support type conversion and validation. """ self._log_types_at_info_if_different(first, second) first = self._convert_to_integer(first, base) second = self._convert_to_integer(second, base) self._should_be_equal(first, second, msg, values) def should_not_be_equal_as_numbers( self, first: object, second: object, msg: "str | None" = None, values: bool = True, precision: int = 6, ): """Fails if objects are equal after converting them to real numbers. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. precision: The precision to round numbers to. The conversion is done with [Convert To Number] keyword using the given `precision`. See [Should Be Equal As Numbers] for examples on how to use `precision` and why it does not always work as expected. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. """ self._log_types_at_info_if_different(first, second) first = self._convert_to_number(first, precision) second = self._convert_to_number(second, precision) self._should_not_be_equal(first, second, msg, values) def should_be_equal_as_numbers( self, first: object, second: object, msg: "str | None" = None, values: bool = True, precision: int = 6, ): """Fails if objects are unequal after converting them to real numbers. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. precision: The precision to round numbers to. The conversion is done with [Convert To Number] keyword using the given `precision`. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. Examples: ```robotframework *** Test Cases *** Should be equal as numbers Should Be Equal As Numbers ${x} 1.1 Should Be Equal As Numbers 1.123 1.1 precision=1 Should Be Equal As Numbers 1.123 1.4 precision=0 Should Be Equal As Numbers 112.3 75 precision=-2 ``` As discussed in the documentation of the [Convert To Number] keyword, machines generally cannot store floating point numbers accurately. Because of this limitation, comparing floats for equality is problematic and the correct approach to use depends on the context. This keyword uses a very naive approach of rounding the numbers before comparing them, which is both prone to rounding errors and does not work very well if numbers are extremely big or small. See [this article][1] for more information about comparing floats, and ideas on how to implement your own context specific comparison algorithm. If you want to avoid possible problems with floating point numbers, you can implement custom keywords using Python's [decimal](http://docs.python.org/library/decimal.html) or [fractions](http://docs.python.org/library/fractions.html) modules. [1]: https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/ """ self._log_types_at_info_if_different(first, second) first = self._convert_to_number(first, precision) second = self._convert_to_number(second, precision) self._should_be_equal(first, second, msg, values) def should_not_be_equal_as_strings( self, first: object, second: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if objects are equal after converting them to strings. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. Strings are always [NFC normalized][NFC]. """ self._log_types_at_info_if_different(first, second) first = safe_str(first) second = safe_str(second) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: first = normalizer.normalize(first) second = normalizer.normalize(second) self._should_not_be_equal(first, second, msg, values) def should_be_equal_as_strings( self, first: object, second: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, formatter: Literal["str", "repr", "ascii"] = "str", collapse_spaces: bool = False, ): """Fails if objects are unequal after converting them to strings. Args: first: The first value to compare. second: The second value to compare. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: Configures optionally stripping spaces. formatter: Formatter to use with values shown in the error message. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. Strings are always [NFC normalized][NFC]. """ self._log_types_at_info_if_different(first, second) first = safe_str(first) second = safe_str(second) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: first = normalizer.normalize(first) second = normalizer.normalize(second) self._should_be_equal(first, second, msg, values, formatter) def should_not_start_with( self, str1: "str | bytes", str2: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the string `str1` starts with the string `str2`. Args: str1: The validated string. str2: The start string to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If the first argument is bytes, the second argument is automatically converted to bytes as well. Support for bytes normalization and bytes auto conversion are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(str1, (bytes, bytearray)): str2 = self._ensure_bytes(str2) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: str1 = normalizer.normalize(str1) str2 = normalizer.normalize(str2) if str1.startswith(str2): raise AssertionError(self._get_msg(str1, str2, msg, values, "starts with")) def should_start_with( self, str1: "str | bytes", str2: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the string `str1` does not start with the string `str2`. Args: str1: The validated string. str2: The start string to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If the first argument is bytes, the second argument is automatically converted to bytes as well. Support for bytes normalization and bytes auto conversion are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(str1, (bytes, bytearray)): str2 = self._ensure_bytes(str2) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: str1 = normalizer.normalize(str1) str2 = normalizer.normalize(str2) if not str1.startswith(str2): raise AssertionError( self._get_msg(str1, str2, msg, values, "does not start with") ) def should_not_end_with( self, str1: "str | bytes", str2: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the string `str1` ends with the string `str2`. Args: str1: The validated string. str2: The end string to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If the first argument is bytes, the second argument is automatically converted to bytes as well. Support for bytes normalization and bytes auto conversion are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(str1, (bytes, bytearray)): str2 = self._ensure_bytes(str2) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: str1 = normalizer.normalize(str1) str2 = normalizer.normalize(str2) if str1.endswith(str2): raise AssertionError(self._get_msg(str1, str2, msg, values, "ends with")) def should_end_with( self, str1: "str | bytes", str2: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the string `str1` does not end with the string `str2`. Args: str1: The validated string. str2: The end string to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If the first argument is bytes, the second argument is automatically converted to bytes as well. Support for bytes normalization and bytes auto conversion are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(str1, (bytes, bytearray)): str2 = self._ensure_bytes(str2) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: str1 = normalizer.normalize(str1) str2 = normalizer.normalize(str2) if not str1.endswith(str2): raise AssertionError( self._get_msg(str1, str2, msg, values, "does not end with") ) def should_not_contain( self, container: Collection, item: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the `container` contains the `item`. Args: container: The container to search the item from. item: The item to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. Works with lists, dictionaries, strings, bytes and anything that supports Python's `in` operator. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If `container` is bytes, `item` is automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should not contain Should Not Contain ${list} item Should Not Contain ${output} FAILED ignore_case=True ``` Automatically converting `item` to bytes, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. """ # TODO: It is inconsistent that errors show original case in 'container' # but 'item' is in lower case. Should rather show original case everywhere # and add separate '(case-insensitive)' note to the error message. # This same logic should be used with all keywords supporting # case-insensitive comparisons. values = self._deprecate_no_values(values) orig = container if isinstance(container, (bytes, bytearray)): item = self._ensure_bytes(item) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: container = normalizer.normalize(container, mapping_to_list=True) item = normalizer.normalize(item) if item in container: raise AssertionError(self._get_msg(orig, item, msg, values, "contains")) def should_contain( self, container: Collection, item: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the `container` does not contain the `item` one or more times. Args: container: The container to search the item from. item: The item to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. Works with lists, dictionaries, strings, bytes and anything that supports Python's `in` operator. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If `container` is bytes, `item` is automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should contain Should Contain ${output} PASS Should Contain ${list} item msg=Item not found values=False Should Contain ${list} item ignore_case=True ``` Automatically converting `item` to bytes is new in Robot Framework 7.1. Support for bytes normalization and recursive normalization with collections are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) orig = container if isinstance(container, (bytes, bytearray)): item = self._ensure_bytes(item) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: container = normalizer.normalize(container, mapping_to_list=True) item = normalizer.normalize(item) if item not in container: raise AssertionError( self._get_msg(orig, item, msg, values, "does not contain") ) def should_contain_any( self, container: Collection, *items: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the `container` does not contain any of the `items`. Args: container: The container to search items from. *items: The items to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. Works with lists, dictionaries, strings, bytes and anything that supports Python's `in` operator. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. All configuration arguments must be given using the `name=value` syntax after all `items`. If `container` is bytes, `items` are automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should contain any Should Contain Any ${string} substring 1 substring 2 Should Contain Any ${list} item 1 item 2 item 3 Should Contain Any ${list} item 1 item 2 item 3 ignore_case=True Should Contain Any ${list} @{items} msg=Custom message values=False ``` Automatically converting `items` to bytes, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if not items: raise RuntimeError("One or more item required.") if isinstance(container, (bytes, bytearray)): items = [self._ensure_bytes(i) for i in items] orig = container normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: container = normalizer.normalize(container, mapping_to_list=True) items = normalizer.normalize(items) if not any(item in container for item in items): raise AssertionError( self._get_msg( orig, seq2str(items, lastsep=" or "), msg, values, "does not contain any of", quote_item2=False, ) ) def should_not_contain_any( self, container: Collection, *items: object, msg: "str | None" = None, values: bool = True, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the `container` contains one or more of the `items`. Args: container: The container to search items from. *items: The items to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. Works with lists, dictionaries, strings, bytes and anything that supports Python's `in` operator. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. All configuration arguments must be given using `name=value` syntax after all `items`. If `container` is bytes, `items` are automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should not contain any Should Not Contain Any ${string} substring 1 substring 2 Should Not Contain Any ${list} item 1 item 2 item 3 Should Not Contain Any ${list} item 1 item 2 item 3 ignore_case=True Should Not Contain Any ${list} @{items} msg=Custom message values=False ``` Automatically converting `items` to bytes, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if not items: raise RuntimeError("One or more item required.") orig = container if isinstance(container, (bytes, bytearray)): items = [self._ensure_bytes(i) for i in items] normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: container = normalizer.normalize(container, mapping_to_list=True) items = normalizer.normalize(items) if any(item in container for item in items): raise AssertionError( self._get_msg( orig, seq2str(items, lastsep=" or "), msg, values, "contains one or more of", quote_item2=False, ) ) def should_contain_x_times( self, container: Collection, item: object, count: int, msg: "str | None" = None, ignore_case: bool = False, strip_spaces: StripSpaces = False, collapse_spaces: bool = False, ): """Fails if the `container` does not contain the `item` `count` times. Args: container: The container to search the item from. item: The item to search for. count: How many times the item should exist. msg: The custom error message. ignore_case: If true, comparison is case-insensitive. strip_spaces: How to optionally strip spaces. collapse_spaces: If true, spaces are collapsed. Works with lists, strings and all objects that [Get Count] works with. See the [Controlling failure messages] section for information about overriding the default failure message with the `msg` argument. The [String and bytes normalization] section explains how `ignore_case`, `strip_spaces` and `collapse_spaces` can be used for normalizing values before comparison. If `container` is bytes, `item` is automatically converted to bytes as well. Examples: ```robotframework *** Test Cases *** Should contain x times Should Contain X Times ${output} hello count=2 Should Contain X Times ${list} item 3 ignore_case=True ``` Automatically converting `item` to bytes, bytes normalization support and recursive normalization with collections are new in Robot Framework 7.4. """ count = self._convert_to_integer(count) orig = container if isinstance(container, (bytes, bytearray)): item = self._ensure_bytes(item) normalizer = Normalizer( ignore_case=ignore_case, strip_spaces=strip_spaces, collapse_spaces=collapse_spaces, ) if normalizer: container = normalizer.normalize(container, mapping_to_list=True) item = normalizer.normalize(item) x = self.get_count(container, item) if not msg: msg = ( f"{orig!r} contains '{item}' {x} time{s(x)}, " f"not {count} time{s(count)}." ) self.should_be_equal_as_integers(x, count, msg, values=False) def get_count(self, container: Collection, item: object) -> int: """Returns and logs how many times the `item` is found from the `container`. Args: container: The container to search the item from. item: The item to search for. Returns: The number of occurrences. This keyword works with Python lists, strings and all objects that either have the `count` method or can be converted to Python lists. Example: ```robotframework *** Test Cases *** Get count ${count} = Get Count ${list} item ``` """ if not hasattr(container, "count"): try: container = list(container) except Exception: raise RuntimeError( f"Converting '{container}' to list failed: {get_error_message()}" ) count = container.count(item) logger.info(f"Item found from container {count} time{s(count)}.") return count def should_not_match( self, string: "str | bytes", pattern: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, ): """Fails if the given `string` matches the given `pattern`. Args: string: The string to match against the pattern. pattern: The glob pattern to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. The `pattern` is considered to be a glob pattern where `*`, `?` and `[chars]` act as wildcards. See the [Glob patterns] section for more information. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. Support for bytes is new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(string, bytes): string = string.decode("latin-1") if isinstance(pattern, bytes): pattern = pattern.decode("latin-1") if self._matches(string, pattern, caseless=ignore_case): raise AssertionError(self._get_msg(string, pattern, msg, values, "matches")) def should_match( self, string: "str | bytes", pattern: "str | bytes", msg: "str | None" = None, values: bool = True, ignore_case: bool = False, ): """Fails if the given `string` does not match the given `pattern`. Args: string: The string to match against the pattern. pattern: The glob pattern to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. ignore_case: If true, comparison is case-insensitive. The `pattern` is considered to be a glob pattern where `*`, `?` and `[chars]` act as wildcards. See the [Glob patterns] section for more information. See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. Support for bytes is new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(string, bytes): string = string.decode("latin-1") if isinstance(pattern, bytes): pattern = pattern.decode("latin-1") if not self._matches(string, pattern, caseless=ignore_case): raise AssertionError( self._get_msg(string, pattern, msg, values, "does not match") ) def should_match_regexp( self, string: "str | bytes", pattern: "str | bytes", msg: "str | None" = None, values: bool = True, flags: "str | None" = None, ) -> "str | bytes | list[str] | list[bytes]": r"""Fails if the `string` does not match the regular expression `pattern`. Args: string: The string to match against the pattern. pattern: The regular expression pattern to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. flags: Optional regular expression flags. Returns: The portion of the string that matched the pattern. If the pattern has groups like `ID: (.*)`, the return value is a list where the first item is the full match and subsequent items are the captured groups. See the [Regular expressions] section for more information about regular expressions and how to use then in Robot Framework test data. Notice that the given pattern does not need to match the whole string. For example, the pattern `ello` matches the string `Hello world!`. If a full match is needed, the `^` and `$` characters can be used to denote the beginning and end of the string, respectively. For example, `^ello$` only matches the exact string `ello`. Possible flags altering how the expression is parsed (e.g. `re.IGNORECASE`, `re.MULTILINE`) can be given using the `flags` argument (e.g. `flags=IGNORECASE | MULTILINE`) or embedded to the pattern (e.g. `(?im)pattern`). See the [Controlling failure messages] section for information about overriding the default failure message with `msg` and `values` arguments. If the first argument is bytes, the second is automatically converted to bytes as well. Examples: ```robotframework *** Variables *** ${STRING} Name: Robot, ID: 42, URL: http://robotframework.org *** Test Cases *** Partial match Should Match Regexp ${STRING} ID: \\d{2} Full match Should Match Regexp ${STRING} ^Name: \\w+, ID: \\d{2}, URL: http.*$ Flags Should Match Regexp ${STRING} id: \\d+ flags=IGNORECASE Should Match Regexp ${STRING} (?i)id: \\d+ Return match ${match} = Should Match Regexp ${STRING} ID: \\d+ Should Be Equal ${match} ID: 42 Return match and groups ${match} ${name} ${id} ${url} = ... Should Match Regexp ${STRING} ^Name: (\\w+), ID: (\\d{2}), URL: (http.*)$ Should Be Equal ${match} ${STRING} Should Be Equal ${name} Robot Should Be Equal ${id} 42 Should Be Equal ${url} http://robotframework.org ``` The `flags` argument is new in Robot Framework 6.0. Automatic bytes conversion is new in Robot Framework 7.4. """ values = self._deprecate_no_values(values) if isinstance(string, (bytes, bytearray)): pattern = self._ensure_bytes(pattern) res = re.search(pattern, string, flags=parse_re_flags(flags)) if res is None: raise AssertionError( self._get_msg(string, pattern, msg, values, "does not match") ) match = res.group(0) groups = res.groups() if groups: return [match, *groups] return match def should_not_match_regexp( self, string: "str | bytes", pattern: "str | bytes", msg: "str | None" = None, values: bool = True, flags: "str | None" = None, ): """Fails if the `string` matches the regular expression `pattern`. Args: string: The string to match against the pattern. pattern: The regular expression pattern to search for. msg: The custom error message. values: If true, compared values are added to the custom error message. flags: Optional regular expression flags. See [Should Match Regexp] for more information about arguments. """ values = self._deprecate_no_values(values) if isinstance(string, (bytes, bytearray)): pattern = self._ensure_bytes(pattern) if re.search(pattern, string, flags=parse_re_flags(flags)) is not None: raise AssertionError(self._get_msg(string, pattern, msg, values, "matches")) def get_length(self, item: Sized) -> int: """Returns and logs the length of the given item as an integer. Args: item: The item to get the length of. Returns: The length of the item. The item can be anything that has length or size, for example, a string, a list, or a dictionary. For legacy reasons, this keyword supports also other ways to get item length than the standard `len(item)`. These other approaches are deprecated, though, and they will be removed in the future. Examples: ```robotframework *** Test Cases *** Get length ${length} = Get Length Hello, world! Should Be Equal ${length} 13 type=int @{list} = Create List Hello, world! ${length} = Get Length ${list} Should Be Equal ${length} 2 type=int ``` See also [Length Should Be], [Should Be Empty] and [Should Not Be Empty]. """ length, deprecated = self._get_length(item) if deprecated: # Deprecated in RF 7.4. TODO: Remove in RF 9. logger.warn( f"Using '{deprecated}' for getting object length is deprecated. " f"Only 'len(obj)' will be supported in the future." ) logger.info(f"Length is {length}.") return length def _get_length(self, item: Any) -> "tuple[int, str | None]": try: return len(item), None except Exception: try: return item.length(), "item.length()" except Exception: try: return item.size(), "item.size()" except Exception: try: return item.length, "item.length" except Exception: raise RuntimeError(f"Could not get length of '{item}'.") def length_should_be(self, item: Collection, length: int, msg: "str | None" = None): """Verifies that the length of the given item is correct. Args: item: The item to validate. length: The expected item length. msg: The custom error message. The length of the item is got using the [Get Length] keyword. The default error message can be overridden with the `msg` argument. """ actual = self.get_length(item) if actual != length: raise AssertionError( msg or f"Length of '{item}' should be {length} but is {actual}." ) def should_be_empty(self, item: Collection, msg: "str | None" = None): """Verifies that the given item is empty. Args: item: The item to validate. msg: The custom error message. The length of the item is got using the [Get Length] keyword. The default error message can be overridden with the `msg` argument. """ if self.get_length(item) > 0: raise AssertionError(msg or f"'{item}' should be empty.") def should_not_be_empty(self, item: Collection, msg: "str | None" = None): """Verifies that the given item is not empty. Args: item: The item to validate. msg: The custom error message. The length of the item is got using the [Get Length] keyword. The default error message can be overridden with the `msg` argument. """ if self.get_length(item) == 0: raise AssertionError(msg or f"'{item}' should not be empty.") def _get_msg( self, item1: object, item2: object, custom_message: "str | None", include_values: bool, delimiter: str, quote_item1: bool = True, quote_item2: bool = True, ): if custom_message and not include_values: return custom_message item1 = f"'{safe_str(item1)}'" if quote_item1 else safe_str(item1) item2 = f"'{safe_str(item2)}'" if quote_item2 else safe_str(item2) default_message = f"{item1} {delimiter} {item2}" if not custom_message: return default_message return f"{custom_message}: {default_message}" class _Variables(_BuiltInBase): def get_variables(self, no_decoration: bool = False) -> NormalizedDict: r"""Returns a dictionary containing all variables in the current scope. Args: no_decoration: If true, variable names are returned without the `${}`, `@{}` and `&{}` decoration. Returns: A dictionary containing variables in the current scope. Variables are returned as a special dictionary that allows accessing variables in space, case, and underscore insensitive manner similarly as accessing variables in the data. This dictionary supports all same operations as normal Python dictionaries and, for example, Collections library can be used to access or modify it. Modifying the returned dictionary has no effect on the variables available in the current scope. Variables are returned with the `${}`, `@{}` or `&{}` decoration based on variable types by default. Giving a true value to the `no_decoration` argument allows getting variables without decoration. Example: ```robotframework *** Test Cases *** Get variables VAR ${variable} value ${variables} = Get Variables Dictionary Should Contain Key ${variables} \${variable} Dictionary Should Contain Key ${variables} \${VARIABLE} ${variables} = Get Variables no_decoration=True Dictionary Should Contain Key ${variables} variable Dictionary Should Contain Key ${variables} VARIABLE ``` """ return self._variables.as_dict(decoration=not no_decoration) @run_keyword_variant(resolve=0) def get_variable_value(self, name: str, default: object = None) -> object: r"""Returns variable value or `default` if the variable does not exist. Args: name: The variable name. default: The default value to return if the variable does not exist. Returns: The variable value, or the default if the variable does not exist. The name of the variable can be given either as a normal variable name like `${name}` or in escaped format like `$name` or `\${name}`. For the reasons explained in the [Using variables with keywords creating or accessing variables] section, using the escaped format is recommended. Notice that `default` must be given positionally like `example` and not using the named-argument syntax like `default=example`. Examples: ```robotframework *** Test Cases *** Get variable value ${value} = Get Variable Value $name default value ``` """ try: name = self._get_var_name(name, require_assign=False) return self._variables.replace_scalar(name) except VariableError: return self._variables.replace_scalar(default) def log_variables(self, level: logger.LogLevel = "INFO"): """Logs all variables in the current scope with the given log level. Args: level: The log level to use. """ variables = self.get_variables() for name in sorted(variables, key=lambda s: s[2:-1].casefold()): name, value = self._get_logged_variable(name, variables) msg = format_assign_message(name, value, cut_long=False) logger.write(msg, level) def _get_logged_variable( self, name: str, variables: Mapping, ) -> "tuple[str, object]": value = variables[name] try: if name[0] == "@": if isinstance(value, Sequence): value = list(value) else: # Don't consume iterables. name = "$" + name[1:] if name[0] == "&": value = dict(value) except Exception: name = "$" + name[1:] return name, value @run_keyword_variant(resolve=0) def variable_should_exist(self, name: str, message: "str | None" = None): r"""Fails if the given variable does not exist in the current scope. Args: name: The variable name. message: The custom error message. The name of the variable can be given either as a normal variable name like `${name}` or in escaped format like `$name` or `\${name}`. For the reasons explained in the [Using variables with keywords creating or accessing variables] section, using the escaped format is recommended. The default error message can be overridden with the `message` argument. Notice that it must be given positionally like `A message` and not using the named-argument syntax like `message=A message`. See also [Variable Should Not Exist] and [Keyword Should Exist]. """ name = self._get_var_name(name) try: self._variables.replace_scalar(name) except VariableError: if message: message = self._variables.replace_string(message) else: message = f"Variable '{name}' does not exist." raise AssertionError(message) @run_keyword_variant(resolve=0) def variable_should_not_exist(self, name: str, message: "str | None" = None): r"""Fails if the given variable exists within the current scope. Args: name: The variable name. message: The custom error message. The name of the variable can be given either as a normal variable name like `${name}` or in escaped format like `$name` or `\${name}`. For the reasons explained in the [Using variables with keywords creating or accessing variables] section, using the escaped format is recommended. The default error message can be overridden with the `message` argument. Notice that it must be given positionally like `A message` and not using the named-argument syntax like `message=A message`. See also [Variable Should Exist] and [Keyword Should Exist]. """ name = self._get_var_name(name) try: self._variables.replace_scalar(name) except VariableError: pass else: if message: message = self._variables.replace_string(message) else: message = f"Variable '{name}' exists." raise AssertionError(message) def replace_variables(self, text: str) -> "str | object": """Replaces variables in the given text with their current values. Args: text: The text to replace variables in. Returns: The text with variables replaced. If the text contains only a single variable, its value is returned as-is, and it can be any object. Otherwise, this keyword always returns a string. If `text` contains undefined variables, this keyword fails. Example: ```robotframework *** Variables *** ${TEMPLATE} Hello, \\${name}! *** Test Cases *** Replace variables VAR ${name} Robot ${result} = Replace Variables ${template} Should Be Equal ${result} Hello, Robot! VAR ${name} world ${result} = Replace Variables ${template} Should Be Equal ${result} Hello, world! ``` """ return self._variables.replace_scalar(text) def set_variable(self, *values: object) -> "object | list[object]": """Returns the given values which can then be assigned to a variable. Args: *values: The value or values to assign. Returns: The value or values to assign. > [!WARNING] > This keyword is considered deprecated and the [VAR syntax] > introduced in Robot Framework 7.0 should be used instead. Examples: ```robotframework *** Test Cases *** Set variable ${hi} = Set Variable Hello, world! ${hi2} = Set Variable I said: ${hi} ${var1} ${var2} = Set Variable Hello world ${item1} ${item2} = Set Variable ${list with 2 items} ``` Variables created with this keyword are available only in the scope where they are created. See [Set Global Variable], [Set Test Variable] and [Set Suite Variable] for information on how to set variables so that they are available also in a larger scope. """ if len(values) == 0: return "" if len(values) == 1: return values[0] return list(values) @run_keyword_variant(resolve=0) def set_local_variable(self, name: str, /, *values: object): r"""Makes the variable available everywhere within the local scope. Args: name: The variable name. *values: The variable value. > [!TIP] > The [VAR syntax] introduced in Robot Framework 7.0 is generally > recommended over this keyword. Variables set with this keyword are available within the local scope of the currently executed test case or in the local scope of the keyword in which they are defined. For example, if you set a variable in a user keyword, it is available only in that keyword. Other test cases or keywords will not see variables set with this keyword. Examples: ```robotframework *** Test Cases *** Set local variable Set Local Variable $name value Set Local Variable @list item1 item2 item3 ``` The main use case for this keyword is creating local variables in libraries or listeners. See the [Set Suite Variable] keyword for more information and usage examples. See also the [Using variables with keywords creating or accessing variables] section for information why it is recommended to give the variable name in escaped format like `$name` instead of the normal `${name}`. See also [Set Global Variable] and [Set Test Variable]. """ name = self._get_var_name(name) value = self._get_var_value(name, values) self._variables.set_local(name, value) self._log_set_variable(name, value) @run_keyword_variant(resolve=0) def set_test_variable(self, name: str, /, *values: object): """Makes the variable available everywhere within the scope of the current test. Args: name: The variable name. *values: The variable value. > [!TIP] > The [VAR syntax] introduced in Robot Framework 7.0 is generally > recommended over this keyword. Variables set with this keyword are available everywhere within the scope of the currently executed test case. For example, if you set a variable in a user keyword, it is available both in the test case level and also in all other user keywords used in the current test. Other test cases will not see variables set with this keyword. If this keyword is used in a suite setup, the variable is available everywhere within that suite setup as well as in the corresponding suite teardown, but it is not seen by tests or possible child suites. If the keyword is used in a suite teardown, the variable is available only in that teardown. Prior to Robot Framework 7.2, using this keyword in a suite setup or teardown was an error. See the [Set Suite Variable] keyword for more information and usage examples. See also the [Using variables with keywords creating or accessing variables] section for information why it is recommended to give the variable name in escaped format like `$name` instead of the normal `${name}`. When creating automated tasks, not tests, it is possible to use [Set Task Variable]. See also [Set Global Variable] and [Set Local Variable]. """ name = self._get_var_name(name) value = self._get_var_value(name, values) self._variables.set_test(name, value) self._log_set_variable(name, value) @run_keyword_variant(resolve=0) def set_task_variable(self, name: str, /, *values: object): """Makes the variable available everywhere within the scope of the current task. Args: name: Variable name. *values: Variable value. > [!TIP] > The [VAR syntax] introduced in Robot Framework 7.0 is generally > recommended over this keyword. This is an alias for [Set Test Variable] that is more applicable when creating tasks, not tests. """ self.set_test_variable(name, *values) @run_keyword_variant(resolve=0) def set_suite_variable(self, name: str, /, *values: object): """Makes the variable available everywhere within the scope of the current suite. Args: name: Variable name. *values: Variable value. > [!TIP] > The [VAR syntax] introduced in Robot Framework 7.0 is generally > recommended over this keyword. Variables set with this keyword are available everywhere within the scope of the currently executed test suite. Setting variables with this keyword thus has the same effect as creating them using the Variables section in the data file or importing them from variable files. Possible child test suites do not see variables set with this keyword by default, but that can be controlled by using `children=<option>` as the last argument. If the specified `<option>` is given a true value, the variable is set also to the child suites. Parent and sibling suites will never see variables set with this keyword. The name of the variable can be given either as a normal variable name like `${NAME}` or in escaped format as `\\${NAME}` or `$NAME`. For the reasons explained in the [Using variables with keywords creating or accessing variables] section, *using the escaped format is highly recommended*. Variable value can be specified using the same syntax as when variables are created in the Variables section. Same way as in that section, it is possible to create scalar values, lists and dictionaries. The type is got from the variable name prefix `$`, `@` and `&`, respectively. If a variable already exists within the new scope, its value will be overwritten. If a variable already exists within the current scope, the value can be left empty and the variable within the new scope gets the value within the current scope. Examples: ```robotframework *** Test Cases *** Set suite variable Set Suite Variable $SCALAR Hello, world! Set Suite Variable $SCALAR Hello, world! children=True Set Suite Variable @LIST First item Second item Set Suite Variable &DICT key=value foo=bar ${ID} = Get ID Set Suite Variable $ID ``` To override an existing value with an empty value, use built-in variables `${EMPTY}`, `@{EMPTY}` or `&{EMPTY}`: ```robotframework *** Test Cases *** Setting empty value Set Suite Variable $SCALAR ${EMPTY} Set Suite Variable @LIST @{EMPTY} Set Suite Variable &DICT &{EMPTY} ``` See also [Set Global Variable], [Set Test Variable] and [Set Local Variable]. """ name = self._get_var_name(name) if ( values and isinstance(values[-1], str) and values[-1].startswith("children=") ): children = self._variables.replace_scalar(values[-1][9:]) children = is_truthy(children) values = values[:-1] else: children = False value = self._get_var_value(name, values) self._variables.set_suite(name, value, children=children) self._log_set_variable(name, value) @run_keyword_variant(resolve=0) def set_global_variable(self, name: str, /, *values: object): r"""Makes the variable available globally in all tests and suites. Args: name: The variable name. *values: The variable value. > [!TIP] > The [VAR syntax] introduced in Robot Framework 7.0 is generally > recommended over this keyword. Variables set with this keyword are globally available in all subsequent test suites, test cases and user keywords. Also variables created in the Variables section are overridden. Variables assigned locally based on keyword return values or by using [Set Suite Variable], [Set Test Variable] or [Set Local Variable] override these variables in that scope, but the global value is not changed in those cases. In practice setting variables with this keyword has the same effect as using command line options `--variable` and `--variablefile`. Because this keyword can change variables everywhere, it should be used with care. See [Set Suite Variable] for more information and usage examples. See also the [Using variables with keywords creating or accessing variables] section for information why it is recommended to give the variable name in escaped format like `$name` instead of the normal `${name}`. """ name = self._get_var_name(name) value = self._get_var_value(name, values) self._variables.set_global(name, value) self._log_set_variable(name, value) # Helpers def _get_var_name(self, original: str, require_assign: bool = True) -> str: try: replaced = self._variables.replace_string(original) except VariableError: replaced = original try: name = self._resolve_var_name(replaced) except ValueError: name = original match = search_variable(name, identifiers="$@&") match.resolve_base(self._variables) valid = match.is_assign() if require_assign else match.is_variable() if not valid: raise DataError(f"Invalid variable name '{name}'.") return str(match) def _resolve_var_name(self, name: str) -> str: if name.startswith("\\"): name = name[1:] if len(name) < 2 or name[0] not in "$@&": raise ValueError if name[1] != "{": name = f"{name[0]}{{{name[1:]}}}" match = search_variable(name, identifiers="$@&", ignore_errors=True) match.resolve_base(self._variables) if not match.is_assign(): raise ValueError return str(match) def _get_var_value(self, name: str, values: Sequence) -> object: if not values: return self._variables[name] if name[0] == "$": # We could consider catenating values similarly as when creating # scalar variables in the variable table, but that would require # handling non-string values somehow. For details see # https://github.com/robotframework/robotframework/issues/1919 if len(values) != 1 or is_list_variable(values[0]): raise DataError( f"Setting list value to scalar variable '{name}' is not supported " f"anymore. Create list variable '@{name[1:]}' instead." ) return self._variables.replace_scalar(values[0]) resolver = VariableResolver.from_name_and_value(name, values) return resolver.resolve(self._variables) def _log_set_variable(self, name: str, value: object): if self._context.steps: logger.info(format_assign_message(name, value)) class _RunKeyword(_BuiltInBase): @run_keyword_variant(resolve=0, dry_run=True) def run_keyword(self, name: KeywordName, /, *args: KeywordArgument) -> object: """Executes the given keyword with the given arguments. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword. This keyword makes it possible to execute different keywords dynamically. The name and arguments of the keyword to execute can be got, for example, from another keyword, from user keyword arguments or from the command line. Examples: ```robotframework *** Test Cases *** Name got from another keyword ${name} = Some Keyword Run Keyword ${name} Name got from arguments [Template] Validate number conversion Integer 20 ${20} Binary 20 10100 Octal 20 24 Hex 20 14 *** Keywords *** Validate number conversion [Arguments] ${kind} ${input} ${expected} ${result} = Run Keyword Convert To ${kind} ${input} Should Be Equal ${result} ${expected} ``` """ ctx = self._context name, args = self._replace_variables_in_name(name, args, ctx) if not isinstance(name, str): raise RuntimeError("Keyword name must be a string.") if ctx.steps: data, result, _ = ctx.steps[-1] lineno = data.lineno else: # Called, typically by a listener, when no keyword started. data = lineno = None if ctx.test: result = ctx.test elif not ctx.suite.has_tests: result = ctx.suite.setup else: result = ctx.suite.teardown kw = Keyword(name, args=args, parent=data, lineno=lineno) with ctx.paused_timeouts: return kw.run(result, ctx) def _replace_variables_in_name(self, name, args, ctx): match = search_variable(name) if not match or ctx.dry_run: return unescape(name), args if match.is_list_variable(): return self._replace_variables_in_name_with_list_variable(name, args, ctx) # If the matched runner accepts embedded arguments, use the original name # instead of the one where variables are already replaced and converted to # strings. This allows using non-string values as embedded arguments also # in this context. An exact match after variables have been replaced has # a precedence over a possible embedded match with the original name, though. # TODO: This functionality exists also in 'KeywordRunner.run'. Reuse that to # avoid duplication. We probably could pass an argument like 'dynamic_name=True' # to 'Keyword.run', but then it would be better if 'Run Keyword' would support # 'NONE' as a special value to not run anything similarly as setup/teardown. replaced = ctx.variables.replace_scalar(name, ignore_errors=ctx.in_teardown) if self._accepts_embedded(replaced, ctx) and self._accepts_embedded(name, ctx): return name, args return replaced, args def _accepts_embedded(self, name, ctx): runner = ctx.get_runner(name, recommend_on_failure=False) return hasattr(runner, "embedded_args") def _replace_variables_in_name_with_list_variable(self, name, args, ctx): # TODO: This seems to be the only place where `replace_until` is used. # That functionality should be removed from `replace_list` and implemented # here. Alternatively we could disallow passing name as a list variable. resolved = ctx.variables.replace_list( [name, *args], replace_until=1, ignore_errors=ctx.in_teardown, ) if not resolved: raise DataError( f"Keyword name missing: Given arguments {[name, *args]} resolved " f"to an empty list." ) return resolved[0], resolved[1:] @run_keyword_variant(resolve=0, dry_run=True) def run_keywords(self, *names_and_args: "KeywordName | KeywordArgument"): """Executes all the given keywords in a sequence. Args: names_and_args: Keywords and their arguments to execute. 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: ```robotframework *** Test Cases *** Only keywords 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 keyword calls. 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: ```robotframework *** Test Cases *** Keywords and arguments Run Keywords ... Initialize Database db1 AND ... Start Servers server1 server2 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`. """ self._run_keywords(self._split_run_keywords(names_and_args)) def _run_keywords(self, iterable): errors = [] for kw, args in iterable: try: self.run_keyword(kw, *args) except ExecutionPassed as err: err.set_earlier_failures(errors) raise except ExecutionFailed as err: errors.extend(err.get_errors()) if not err.can_continue(self._context): break if errors: raise ExecutionFailures(errors) def _split_run_keywords(self, keywords): if "AND" not in keywords: for name in self._split_run_keywords_without_and(keywords): yield name, () else: for kw_call in self._split_run_keywords_with_and(keywords): if not kw_call: raise DataError("AND must have keyword before and after.") yield kw_call[0], kw_call[1:] def _split_run_keywords_without_and(self, keywords): replace_list = self._variables.replace_list ignore_errors = self._context.in_teardown # `run_keyword` resolves variables, but list variables must be expanded # here to pass it each keyword name separately. for name in keywords: if is_list_variable(name): for n in replace_list([name], ignore_errors=ignore_errors): yield escape(n) else: yield name def _split_run_keywords_with_and(self, keywords): while "AND" in keywords: index = keywords.index("AND") yield keywords[:index] keywords = keywords[index + 1 :] yield keywords @run_keyword_variant(resolve=1, dry_run=True) def run_keyword_if( self, condition: Expression, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword with the given arguments, if `condition` is true. Args: condition: The condition to evaluate. name: Keyword to run if the condition is true. *args: Arguments passed to the keyword. Returns: Return value of the executed keyword or the `None` object if the keyword is not executed. > [!TIP] > The [IF/ELSE syntax] introduced in Robot Framework 4.0 is generally > recommended over 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: ```robotframework *** Test Cases *** Simple if/else 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: ```robotframework *** Test Cases *** Special variable syntax 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. The simple if/else in the earlier example could also be created like this: ```robotframework *** Test Cases *** Simple if/else, take 2 Run Keyword If "${status}" == "PASS" ... Some Action arg ... ELSE ... Another Action ``` 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`. """ args, branch = self._split_elif_or_else_branch(args) if self._is_true(condition): return self.run_keyword(name, *args) return branch() def _split_elif_or_else_branch(self, args): if "ELSE IF" in args: args, branch = self._split_branch( args, "ELSE IF", 2, "condition and keyword" ) return args, lambda: self.run_keyword_if(*branch) if "ELSE" in args: args, branch = self._split_branch(args, "ELSE", 1, "keyword") return args, lambda: self.run_keyword(*branch) return args, lambda: None def _split_branch(self, args, control_word, required, required_error): index = list(args).index(control_word) branch = self._variables.replace_list(args[index + 1 :], required) if len(branch) < required: raise DataError(f"{control_word} requires {required_error}.") return args[:index], branch @run_keyword_variant(resolve=1, dry_run=True) def run_keyword_unless( self, condition: Expression, name: KeywordName, /, *args: KeywordArgument, ) -> object: """*DEPRECATED since RF 5.0. Use native IF/ELSE or `Run Keyword If` instead.* Args: condition: The condition to evaluate. name: The keyword to run if the condition is false. *args: Arguments passed to the keyword. Returns: Return value of the executed keyword or the `None` object if the keyword is not executed. """ if self._is_true(condition): return None return self.run_keyword(name, *args) @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_and_ignore_error( self, name: KeywordName, /, *args: KeywordArgument, ) -> "tuple[Literal['PASS', 'FAIL'], object]": """Runs the given keyword with the given arguments and ignores possible errorw. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: If keyword succeeds, returns string `PASS` and the keyword return value. If the keyword fails, returns string `FAIL` and the error message. > [!TIP] > The [TRY/EXCEPT syntax] introduced in Robot Framework 5.0 is > generally recommended over this keyword. Use [Run Keyword And Return Status] if you are only interested in the execution status. Errors caused by invalid syntax, timeouts or fatal exceptions are not caught by this keyword, but otherwise this keyword never fails. """ try: return "PASS", self.run_keyword(name, *args) except ExecutionFailed as err: if err.dont_continue or err.skip: raise return "FAIL", str(err) @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_and_warn_on_failure( self, name: KeywordName, /, *args: KeywordArgument, ) -> "tuple[Literal['PASS', 'FAIL'], object]": """Runs the specified keyword logs a warning if the keyword fails. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: If keyword succeeds, returns string `PASS` and the keyword return value. If the keyword fails, returns string `FAIL` and the error message. > [!TIP] > The [TRY/EXCEPT syntax] introduced in Robot Framework 5.0 is > generally recommended over this keyword. 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. Errors caused by invalid syntax, timeouts or fatal exceptions are not caught by this keyword, but otherwise this keyword never fails. """ status, ret_or_err = self.run_keyword_and_ignore_error(name, *args) if status == "FAIL": logger.warn(f"Executing keyword '{name}' failed:\n{ret_or_err}") return status, ret_or_err @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_and_return_status( self, name: KeywordName, /, *args: KeywordArgument, ) -> bool: """Runs the specified keyword and returns the status as a Boolean value. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: Boolean `True` if the keyword succeeded, `False` otherwise. > [!TIP] > The [TRY/EXCEPT syntax] introduced in Robot Framework 5.0 is > generally recommended over this keyword. Errors caused by invalid syntax, timeouts or fatal exceptions are not caught by this keyword, but otherwise this keyword never fails. """ status, _ = self.run_keyword_and_ignore_error(name, *args) return status == "PASS" @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_and_continue_on_failure( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the keyword and continues execution even if a failure occurs. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword. Execution can continue even if the executed keyword would fail, but the test or task will be marked failed when it finishes. Execution can continue even if another continuable failure occurs, but it ends immediately if there is a normal failure. Example: ```robotframework *** Test Cases *** Run keyword and continue on failure 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 a fatal exception. """ try: return self.run_keyword(name, *args) except ExecutionFailed as err: if not err.dont_continue: err.continue_on_failure = True raise @run_keyword_variant(resolve=1, dry_run=True) def run_keyword_and_expect_error( self, expected_error: str, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the keyword and checks that the expected error occurred. Args: expected_error: The expected error message or pattern. name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword. > [!TIP] > The [TRY/EXCEPT syntax] introduced in Robot Framework 5.0 is > generally recommended over this keyword. The expected error must be given in the same format as in Robot Framework reports. It is interpreted as a glob pattern with `*`, `?` and `[chars]` as wildcards by default, 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. Useful if the error contains glob wildcards. | | STARTS | Error must start with the specified text. | | REGEXP | Regular expression match. | | GLOB | Glob pattern match (default). | 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: ```robotframework *** Test Cases *** Run keyword and expect error Run Keyword And Expect Error Example 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"] ${error} = Run Keyword And Expect Error ValueError: * ... Keyword arg1 arg2 Log To Console ${error} ``` Errors caused by invalid syntax, timeouts or fatal exceptions are not caught by this keyword. 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 the pattern must nowadays match the error fully. """ try: self.run_keyword(name, *args) except ExecutionFailed as err: if err.dont_continue or err.skip: raise error = err.message else: raise AssertionError(f"Expected error '{expected_error}' did not occur.") if not self._error_is_expected(error, expected_error): raise AssertionError( f"Expected error '{expected_error}' but got '{error}'." ) return error def _error_is_expected(self, error, expected_error): glob = self._matches matchers = { "GLOB": glob, "EQUALS": lambda s, p: s == p, "STARTS": lambda s, p: s.startswith(p), "REGEXP": lambda s, p: re.fullmatch(p, s) is not None, } prefixes = tuple(prefix + ":" for prefix in matchers) if not expected_error.startswith(prefixes): return glob(error, expected_error) prefix, expected_error = expected_error.split(":", 1) return matchers[prefix](error, expected_error.lstrip()) @run_keyword_variant(resolve=1, dry_run=True) def repeat_keyword( self, repeat: "int | str | timedelta", name: KeywordName, /, *args: KeywordArgument, ): """Executes the specified keyword multiple times. Args: repeat: How many times (count) or how long (timeout) to repeat executing the keyword. name: The keyword to execute. *args: Arguments passed to the keyword. If `repeat` is given as count, it specifies how many times the keyword should be executed. A count 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-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`) or given as a `timedelta` object. 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: ```robotframework *** Test Cases *** Repeat as count Repeat Keyword 5 times Go to Previous Page Repeat as timeout Repeat Keyword 2 minutes Some Keyword arg1 arg2 ``` The `timedelta` support is new in Robot Framework 7.4. """ try: count = self._get_repeat_count(repeat) except ValueError: timeout = self._get_repeat_timeout(repeat) if timeout is None: raise keywords = self._keywords_repeated_by_timeout(timeout, name, args) else: keywords = self._keywords_repeated_by_count(count, name, args) self._run_keywords(keywords) def _get_repeat_count(self, times, require_postfix=False): if isinstance(times, timedelta): raise ValueError times = normalize(str(times)) if times.endswith("times"): times = times[:-5] elif times.endswith("x"): times = times[:-1] elif require_postfix: raise ValueError return self._convert_to_integer(times) def _get_repeat_timeout(self, timestr): try: float(timestr) except (ValueError, TypeError): pass else: return None try: return timestr_to_secs(timestr) except ValueError: return None def _keywords_repeated_by_count(self, count, name, args): if count <= 0: logger.info(f"Keyword '{name}' repeated zero times.") for i in range(count): logger.info(f"Repeating keyword, round {i + 1}/{count}.") yield name, args def _keywords_repeated_by_timeout(self, timeout, name, args): if timeout <= 0: logger.info(f"Keyword '{name}' repeated zero times.") round = 0 maxtime = time.time() + timeout while time.time() < maxtime: round += 1 remaining = secs_to_timestr(maxtime - time.time(), compact=True) logger.info(f"Repeating keyword, round {round}, {remaining} remaining.") yield name, args @run_keyword_variant(resolve=2, dry_run=True) def wait_until_keyword_succeeds( self, retry: "int | str | timedelta", retry_interval: "str | timedelta", name: KeywordName, /, *args: KeywordArgument, ): """Runs the specified keyword and retries if it fails. Args: retry: How long (timeout) or how many times (count) to wait for the keyword to succeed. retry_interval: The time to wait between execution attempts name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword. 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`) or given as a `timedelta` object. If `retry` is given as count, it must have a `times` or `x` postfix (e.g. `5 times`, `10 x`). 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: ```robotframework *** Test Cases *** Retry as timeout Wait Until Keyword Succeeds 2 min 5 sec My keyword argument Retry as count Wait Until Keyword Succeeds 3x 200ms My keyword Strict interval Wait Until Keyword Succeeds 3x strict: 200ms My keyword ``` All normal failures are caught by this keyword. Errors caused by invalid syntax, timeouts or fatal exceptions 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 the `--remove-keywords WUKS` command line option. """ maxtime = count = -1 try: count = self._get_repeat_count(retry, require_postfix=True) except ValueError: try: timeout = timestr_to_secs(retry) except ValueError: raise ValueError(f"Invalid retry value '{retry}'.") maxtime = time.time() + timeout message = f"for {secs_to_timestr(timeout)}" else: if count <= 0: raise ValueError(f"Retry count {count} is not positive.") message = f"{count} time{s(count)}" if not ( isinstance(retry_interval, str) and normalize(retry_interval).startswith("strict:") ): strict_interval = False else: retry_interval = retry_interval.split(":", 1)[1].strip() strict_interval = True retry_interval = sleep_time = timestr_to_secs(retry_interval) while True: start_time = time.time() try: return self.run_keyword(name, *args) except ExecutionFailed as err: self._reset_keyword_timeout_in_teardown(err, self._context) if err.dont_continue or err.skip: raise count -= 1 if time.time() > maxtime > 0 or count == 0: name = self._variables.replace_scalar(name) raise AssertionError( f"Keyword '{name}' failed after retrying {message}. " f"The last error was: {err}" ) finally: if strict_interval: execution_time = time.time() - start_time sleep_time = retry_interval - execution_time if sleep_time < 0: logger.warn( f"Keyword execution time {secs_to_timestr(execution_time)} " f"is longer than retry interval " f"{secs_to_timestr(retry_interval)}." ) self._sleep_in_parts(sleep_time) def _reset_keyword_timeout_in_teardown(self, err, context): # Keyword timeouts in teardowns have been converted to normal failures # to allow execution to continue on higher level: # https://github.com/robotframework/robotframework/issues/3398 # We need to reset it here to not continue unnecessarily: # https://github.com/robotframework/robotframework/issues/5237 if context.in_teardown: timeouts = [t for t in context.timeouts if t.kind == "KEYWORD"] if timeouts and min(timeouts).timed_out(): err.keyword_timeout = True @run_keyword_variant(resolve=1) def set_variable_if(self, condition: Expression, /, *values: object) -> object: """Sets variable based on the given condition. Args: condition: The condition to evaluate. *values: Value to assign based on the condition. Returns: First value if condition is true, second value if the condition is false, or a subsequent value if the second value is another condition. > [!TIP] > The [IF/ELSE syntax] in combination with the [VAR syntax] is > recommended over this keyword. 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. 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. ```robotframework *** Test Cases *** Condition and two values ${var} = Set Variable If ${rc} == 0 zero nonzero Multiple conditions and values ${var} = Set Variable If ... ${rc} > 0 greater than zero ... ${rc} < 0 less than zero ... zero ``` """ values = list(values) while True: values = self._verify_values_for_set_variable_if(values) if self._is_true(condition): return self._variables.replace_scalar(values[0]) if len(values) == 1: return None if len(values) == 2: return self._variables.replace_scalar(values[1]) condition, *values = values[1:] condition = self._variables.replace_scalar(condition) def _verify_values_for_set_variable_if(self, values): if not values: raise RuntimeError("At least one value is required.") if is_list_variable(values[0]): values[:1] = [escape(item) for item in self._variables[values[0]]] return self._verify_values_for_set_variable_if(values) return values @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_if_test_failed( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword with the given arguments, if the test failed. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword or `None` if the keyword was not executed. This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error. """ test = self._get_test_in_teardown("Run Keyword If Test Failed") return self.run_keyword(name, *args) if test.failed else None @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_if_test_passed( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword with the given arguments, if the test passed. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword or `None` if the keyword was not executed. This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error. """ test = self._get_test_in_teardown("Run Keyword If Test Passed") return self.run_keyword(name, *args) if test.passed else None @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_if_timeout_occurred( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword if either a test or a keyword timeout has occurred. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword or `None` if the keyword was not executed. This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error. """ self._get_test_in_teardown("Run Keyword If Timeout Occurred") return self.run_keyword(name, *args) if self._context.timeout_occurred else None def _get_test_in_teardown(self, kwname): ctx = self._context if ctx.test and ctx.in_test_teardown: return ctx.test raise RuntimeError(f"Keyword '{kwname}' can only be used in test teardown.") @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_if_all_tests_passed( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword with the given arguments, if all tests passed. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword or `None` if the keyword was not executed. This keyword can only be used in a suite teardown. Trying to use it anywhere else results in an error. """ suite = self._get_suite_in_teardown("Run Keyword If All Tests Passed") return self.run_keyword(name, *args) if suite.statistics.failed == 0 else None @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_if_any_tests_failed( self, name: KeywordName, /, *args: KeywordArgument, ) -> object: """Runs the given keyword with the given arguments, if one or more tests failed. Args: name: The keyword to execute. *args: Arguments passed to the keyword. Returns: The return value of the executed keyword or `None` if the keyword was not executed. This keyword can only be used in a suite teardown. Trying to use it anywhere else results in an error. """ suite = self._get_suite_in_teardown("Run Keyword If Any Tests Failed") return self.run_keyword(name, *args) if suite.statistics.failed > 0 else None def _get_suite_in_teardown(self, kw): if not self._context.in_suite_teardown: raise RuntimeError(f"Keyword '{kw}' can only be used in suite teardown.") return self._context.suite class _Control(_BuiltInBase): def skip(self, msg: str = "Skipped with Skip keyword.") -> NoReturn: """Stops the current test or task and sets its status to SKIP. Args: msg: The message explaining why the test or task was skipped. Possible teardowns are executed. """ raise SkipExecution(msg) def skip_if(self, condition: Expression, msg: "str | None" = None): """Conditionally stops the current test or task and sets its status to SKIP. Args: condition: The condition to evaluate. msg: The message explaining why the test or task was skipped. The default is to use the given `condition`. If the `condition` is true, stops the current test or task and sets its status to SKIP. Possible teardowns are executed. Does nothing if the `condition` is false. """ if self._is_true(condition): raise SkipExecution(msg or condition) def continue_for_loop(self): """Skips the current loop iteration and continues from the next. > [!WARNING] > This keyword is considered deprecated and the [CONTINUE statement] > should be used instead. """ if not self._context.allow_loop_control: raise DataError("'Continue For Loop' can only be used inside a loop.") logger.info("Continuing for loop from the next iteration.") raise ContinueLoop def continue_for_loop_if(self, condition: Expression): """Skips the current loop iteration if the `condition` is true. Args: condition: The condition to evaluate. > [!WARNING] > This keyword is considered deprecated and the [CONTINUE statement] > in combination with the [IF/ELSE syntax] should be used instead. """ if not self._context.allow_loop_control: raise DataError("'Continue For Loop If' can only be used inside a loop.") if self._is_true(condition): self.continue_for_loop() def exit_for_loop(self): """Stops executing the enclosing loop. > [!WARNING] > This keyword is considered deprecated and the [BREAK statement] > should be used instead. """ if not self._context.allow_loop_control: raise DataError("'Exit For Loop' can only be used inside a loop.") logger.info("Exiting for loop altogether.") raise BreakLoop def exit_for_loop_if(self, condition: Expression): """Stops executing the enclosing loop if the `condition` is true. Args: condition: The condition to evaluate. > [!WARNING] > This keyword is considered deprecated and the [BREAK statement] > in combination with the [IF/ELSE syntax] should be used instead. """ if not self._context.allow_loop_control: raise DataError("'Exit For Loop If' can only be used inside a loop.") if self._is_true(condition): self.exit_for_loop() @run_keyword_variant(resolve=0) def return_from_keyword(self, *return_values: object) -> NoReturn: """Returns from the enclosing user keyword. Args: *return_values: The value or values to return. > [!WARNING] > This keyword is considered deprecated and the [RETURN statement] > should be used instead. """ self._return_from_keyword(return_values) def _return_from_keyword(self, return_values=None, failures=None) -> NoReturn: logger.info("Returning from the enclosing user keyword.") raise ReturnFromKeyword(return_values, failures) @run_keyword_variant(resolve=1) def return_from_keyword_if(self, condition: Expression, *return_values: object): """Returns from the enclosing user keyword if `condition` is true. Args: condition: The condition to evaluate. *return_values: Value or values to return. > [!WARNING] > This keyword is considered deprecated and the [RETURN statement] > in combination with the [IF/ELSE syntax] should be used instead. """ if self._is_true(condition): self._return_from_keyword(return_values) @run_keyword_variant(resolve=0, dry_run=True) def run_keyword_and_return( self, name: KeywordName, /, *args: KeywordArgument, ) -> NoReturn: """Runs the specified keyword and returns from the enclosing user keyword. Args: name: The keyword to execute. *args: Arguments passed to the keyword. > [!TIP] > It is recommended to use the [RETURN statement] instead of special > keywords for returning from user keywords. After running the keyword, returns from the enclosing user keyword and passes possible return value from the executed keyword further. Example: ```robotframework *** Keywords *** Run keyword and return Run Keyword And Return My Keyword arg1 arg2 RETURN statement ${result} = My Keyword arg1 arg2 RETURN ${result} ``` """ try: ret = self.run_keyword(name, *args) except ExecutionFailed as err: self._return_from_keyword(failures=[err]) else: self._return_from_keyword(return_values=[escape(ret)]) @run_keyword_variant(resolve=1, dry_run=True) def run_keyword_and_return_if( self, condition: Expression, name: KeywordName, /, *args: KeywordArgument, ): """Conditionally runs the specified keyword and returns from the enclosing user keyword. Args: condition: The condition to evaluate. name: The keyword to run if the condition is true. *args: Arguments passed to the keyword. A wrapper for [Run Keyword And Return] to run and return based on the given `condition`. """ if self._is_true(condition): self.run_keyword_and_return(name, *args) def pass_execution(self, message: str, *tags: str) -> NoReturn: """Stops rest of the current test, setup or teardown and sets status to PASS. Args: message: The message explaining why execution was passed. tags: Tags to set or remove. Tags starting with `-` are removed. This keyword can be used anywhere in the test data, but the place where used affects the behavior: - When used in any setup or teardown (suite, test or keyword), passes that setup or teardown. Possible keyword teardowns of the started keywords are executed. Does not affect execution or statuses otherwise. - When used in a test outside its setup or teardown, passes that particular test case. Possible test and keyword teardowns are executed. Possible continuable failures that occurred before calling this keyword, as well as failures in executed teardowns, will fail the execution. It is mandatory to give a message explaining why execution was passed. The message is considered plain text by default, but starting it with `*HTML*` allows using HTML formatting. It is also possible to modify test tags passing tags after the message similarly as with the [Fail] keyword. Tags starting with a hyphen (e.g. `-regression`) are removed and others added. Tags are modified using [Set Tags] and [Remove Tags] internally, and the semantics setting and removing them are the same as with these keywords. Examples: ```robotframework *** Test Cases *** Pass execution Some Keywords Pass Execution All features available in this version tested. Log This is not executed. Modify tags Pass Execution Deprecated test. deprecated -regression ``` This keyword is typically used conditionally using the [IF/ELSE syntax] or otherwise. The most common cases can be handled also with the [Pass Execution If] keyword. Passing execution in the middle of a test, setup or teardown should be used with care. In the worst case it leads to tests that skip all the parts that could actually uncover problems in the tested application. In cases where execution cannot continue due to external factors, it is often safer to fail the test case instead. """ message = message.strip() if not message: raise RuntimeError("Message cannot be empty.") self._set_and_remove_tags(tags) log_message, level = self._get_logged_test_message_and_level(message) logger.write(f"Execution passed with message:\n{log_message}", level) raise PassExecution(message) @run_keyword_variant(resolve=1) def pass_execution_if(self, condition: Expression, message: str, *tags: str): """Conditionally skips rest of the current test, setup, or teardown with PASS status. Args: condition: The condition to evaluate. message: Message explaining why execution was passed. tags: Tags to set or remove. Tags starting with `-` are removed. A wrapper for [Pass Execution] to skip rest of the current test, setup or teardown based the given `condition`. """ if self._is_true(condition): message = self._variables.replace_string(message) tags = self._variables.replace_list(tags) self.pass_execution(message, *tags) class _Misc(_BuiltInBase): def no_operation(self): """Does absolutely nothing. Useful as a placeholder in places where a block cannot be empty. """ def sleep(self, time_: timedelta, reason: "str | None" = None): """Pauses execution for the given time. Args: time_: The time to sleep. reason: The optional reason for sleeping. Both the time slept and the optional reason are logged. Examples: ```robotframework *** Test Cases *** Sleep Sleep 1.5 Sleep 2 minutes 10 seconds Sleep 10s Wait for a reply ``` > [!WARNING] > The `time_` argument will be renamed to `time` in Robot Framework 8.0. > Users should avoid using the named argument syntax like `time_=1.5` > and pass the time positionally like `1.5` instead. See issue > [#5762](https://github.com/robotframework/robotframework/issues/5762) > for more information. """ seconds = timestr_to_secs(time_) # Python hangs with negative values seconds = max(seconds, 0) self._sleep_in_parts(seconds) logger.info(f"Slept {secs_to_timestr(seconds)}.") if reason: logger.info(reason) def _sleep_in_parts(self, seconds): # time.sleep can't be stopped in windows # to ensure that we can signal stop (with timeout) # split sleeping to small pieces endtime = time.time() + float(seconds) while True: remaining = endtime - time.time() if remaining <= 0: break time.sleep(min(remaining, 0.01)) def catenate(self, *items: str) -> str: r"""Concatenates the given items together and returns the resulted string. Args: items: The items to join together. Returns: The concatenated string. By default, items are joined together with spaces, but if the first item contains the string `SEPARATOR=<sep>`, the separator `<sep>` is used instead. Items are converted into strings when necessary. Concatenating is especially convenient when creating longer strings. In such usage it is typically a good idea to split parts to own lines using the `...` continuation syntax. Examples: ```robotframework *** Test Cases *** Catenate ${string} = Catenate Hello world ${multiline} = Catenate SEPARATOR=\n ... The first line of a somewhat long string. ... The second line. ... The third and the final line. ``` Notice that the [VAR syntax] supports concatenation as well: ```robotframework *** Test Cases *** VAR syntax VAR ${string} Hello world VAR ${multiline} ... The first line of a somewhat long string. ... The second line. ... The third and the final line. ... separator=\n ``` """ if not items: return "" if items[0].startswith("SEPARATOR="): sep = items[0][len("SEPARATOR=") :] items = items[1:] else: sep = " " return sep.join(items) def log( self, message: object, level: logger.LogLevel = "INFO", html: bool = False, console: "bool | None" = None, repr: "Literal['DEPRECATED'] | bool" = "DEPRECATED", formatter: Literal["str", "repr", "ascii", "type", "len"] = "str", ): r"""Logs the given message with the given level. Args: message: The message to log. level: The log level to use. html: If true, the message is considered to be HTML and special characters in messages like `Hello, <b>Robot</b>!` are not escaped. console: Controls logging messages to the console in addition to the log file repr: Deprecated. Use `formatter` instead. formatter: Controls how to format the logged message. Valid levels are TRACE, DEBUG, INFO (default), WARN and ERROR. In addition to that, there are pseudo log levels HTML and CONSOLE that both log messages using the INFO level. Non-string messages are converted to strings automatically. Messages below the current active log level are ignored. See the [Set Log Level] keyword and the `--loglevel` command line option for more details about setting the level. Messages logged with the WARN or ERROR levels are visible also in the "Execution Errors" section in the log file. They are also logged to the console in addition to the log file by default. If the `html` argument is given a true value or the HTML pseudo log level is used, the message is considered to be HTML and special characters such as `<` are not escaped. For example, logging `<img src="image.png">` creates an image in this case, but otherwise the message is that exact string. When using the HTML pseudo level, the messages is logged using the INFO level. The `console` argument controls logging messages to the console in addition to the log file. Messages with the WARN and ERROR level are logged to the console by default and others are not, but that can be changed by setting `console` to `True` or `False`. Another way to log messages to the console is using the CONSOLE pseudo level in which case the message is logged to the log file using the INFO level. If the message should not be logged to the log file or there are special formatting needs, the [Log To Console] keyword can be used instead. The `formatter` argument controls how to format the string representation of the message. Possible values are `str` (default), `repr`, `ascii`, `len`, and `type`. They work similarly to Python built-in functions with same names. When using `repr`, bigger lists, dictionaries and other containers are also pretty-printed so that there is one item per row. For more details see the [String representations] section. The old way to control string representation was using the `repr` argument. This argument has been deprecated and `formatter=repr` should be used instead. Examples: ```robotframework *** Test Cases *** Log Log Hi, world! # Normal INFO message. Log Warning, world! WARN # Warning. Log Hi, <b>Robot</b>! html=True # INFO message as HTML. Log Hi, <b>Robot</b>! HTML # Same as the above. Log Hi, <b>Robot</b>! DEBUG html=True # DEBUG as HTML. Log Hi, console! console=True # Log also to onsole. Log Hi, console! CONSOLE # Same as the above Log Null is \x00 formatter=repr # Log `'Null is \x00'`. ``` See [Log Many] if you want to log multiple messages in one go, and [Log To Console] if you only want to write to the console. Formatter options `type` and `len` are new in Robot Framework 5.0. The CONSOLE pseudo level is new in Robot Framework 6.1. """ # TODO: Remove `repr` altogether in RF 8.0. It was deprecated in RF 5.0. if repr == "DEPRECATED": formatter = self._get_formatter(formatter) else: logger.warn( "The 'repr' argument of 'BuiltIn.Log' is deprecated. " "Use 'formatter=repr' instead." ) formatter = prepr if repr else self._get_formatter(formatter) logger.write(formatter(message), level, html, console) @run_keyword_variant(resolve=0) def log_many(self, *messages: object): """Logs the given messages as separate entries using the INFO level. Args: *messages: Messages to log. Supports also logging list and dictionary variable items individually. Non-string items are converted to strings automatically. Examples: ```robotframework *** Test Cases *** Log many Log Many Hello ${var} Log Many @{list} &{dict} ``` See the [Log] keyword if you want to use other log levels than INFO, log using HTML or log to the console. """ for msg in self._yield_logged_messages(messages): logger.info(msg) def _yield_logged_messages(self, messages): for msg in messages: match = search_variable(msg) value = self._variables.replace_scalar(msg) if match.is_list_variable(): yield from value elif match.is_dict_variable(): for name in value: yield f"{name}={value[name]}" else: yield value def log_to_console( self, message: object, stream: Literal["stdout", "stderr"] = "stdout", no_newline: bool = False, format: "str | None" = None, ): """Logs the given message to the console. Args: message: The message to log. stream: The standard stream to use. no_newline: If true, no newline is added to the message. format: [Format specification] to use. Uses the standard output stream by default. Using the standard error stream is possible by giving the `stream` argument value `stderr` (case-insensitive). Converts non-string messages to strings automatically. Appends a newline to the logged message by default. This can be disabled by giving the `no_newline` argument a true value. It is possible to add alignment and padding by using the `format` argument. See the [format specification] details about the syntax. This argument is new in Robot Framework 5.0. Examples: ```robotframework *** Test Cases *** Log to console Log To Console Hello, console! Log To Console Hello, stderr! stream=STDERR Log To Console Message starts here, and it is no_newline=true Log To Console continued without a newline. Log To Console Aligned to right. format=>42 Log To Console Center aligned with * padding. format=*^60 ``` This keyword does not log the message to the normal log file. Use the [Log] keyword, possibly with the `console` argument , if that is desired. [Format specification]: https://docs.python.org/3/library/string.html#formatspec """ if format: format = "{:" + format + "}" message = format.format(message) logger.console(message, newline=not no_newline, stream=stream) @run_keyword_variant(resolve=0) def comment(self, *messages: str): """Displays the given messages in the log file as keyword arguments. Args: *messages: Messages to show as arguments. This keyword does nothing with the arguments it receives, but as they are visible in the log, this keyword can be used to display simple messages. Given arguments are ignored so thoroughly that they can even contain non-existing variables. If you are interested about variable values, you can use the [Log] or [Log Many] keywords. A difference between this keyword and using the normal `# comment` syntax is that normal comments are not shown in the log file at all. """ def set_log_level(self, level: SettableLevel) -> SettableLevel: """Sets the log threshold to the specified level. Args: level: The log level to set. Returns: The previous log level. Messages below the level will not logged. The default logging level is INFO, but it can be overridden with the `--loglevel` command line option. The available levels are TRACE, DEBUG, INFO (default), WARN, ERROR and NONE (no logging). The old level is returned and can be used for setting the level back later. An alternative way to reset the level is using the dedicated [Reset Log Level] keyword. """ old = self._context.output.set_log_level(level) self._namespace.variables.set_global("${LOG_LEVEL}", level) logger.debug(f"Log level changed from {old} to {level}.") return old def reset_log_level(self) -> SettableLevel: """Resets the log level to the original value. Returns: The previous log level. The original log level is set from the command line with the `--loglevel` option and is INFO by default. The active log level can be changed using the [Set Log Level] keyword. New in Robot Framework 7.0. """ level = self._context.output.initial_log_level return self.set_log_level(level) def reload_library(self, name_or_instance: object): """Rechecks what keywords the specified library provides. Args: name_or_instance: The library reload. This keyword can be used in the data or by a library itself when keywords it provides have changed. The library can be specified by its name or as the active instance of the library. The latter is especially useful if the library itself calls this keyword as a method. """ lib = self._namespace.reload_library(name_or_instance) logger.info(f"Reloaded library {lib.name} with {len(lib.keywords)} keywords.") @run_keyword_variant(resolve=0) def import_library(self, name: str, *args: object): """Imports a library with the given name and optional arguments. Args: name: The library to import. *args: Arguments passed to the library. This functionality allows dynamic importing of libraries while tests are running. That may be necessary, if the library itself is dynamic and not yet available when test data is processed. In a normal case, libraries should be imported using the Library setting in the Setting section. This keyword supports importing libraries both using library names and physical paths. When paths are used, they must be given in absolute format or found from [search path]. Forward slashes can be used as path separators in all operating systems. It is possible to pass arguments to the imported library and also named argument syntax works if the library supports it. `AS` syntax can be used to give a custom name to the imported library. Examples: ```robotframework *** Test Cases *** Import library Import Library MyLibrary Import Library ${CURDIR}/Lib.py arg1 named=arg2 AS Custom ``` """ args, alias = self._split_alias(args) try: self._namespace.import_library(name, args, alias) except DataError as err: raise RuntimeError(str(err)) def _split_alias(self, args): if len(args) > 1 and normalize_whitespace(args[-2]) in ("WITH NAME", "AS"): return args[:-2], args[-1] return args, None @run_keyword_variant(resolve=0) def import_variables(self, path: str, *args: object): """Imports a variable file with the given path and optional arguments. Args: path: The variable file to import. *args: Arguments passed to the variable file. Variables imported with this keyword are set into the test suite scope similarly when importing them in the Setting table using the Variables setting. These variables override possible existing variables with the same names. This functionality can thus be used to import new variables, for example, for each test in a test suite. The given path must be absolute or found from [search path]. Forward slashes can be used as path separator regardless the operating system. Examples: ```robotframework *** Test Cases *** Import variables Import Variables ${CURDIR}/variables.py Import Variables ${CURDIR}/../vars/env.py arg1 arg2 Import Variables file_from_search_path.py ``` """ try: self._namespace.import_variables(path, list(args), overwrite=True) except DataError as err: raise RuntimeError(str(err)) @run_keyword_variant(resolve=0) def import_resource(self, path: str): """Imports a resource file with the given path. Args: path: The resource file to import. Resources imported with this keyword are set into the test suite scope similarly when importing them in the Setting table using the Resource setting. The given path must be absolute or found from [search path]. Forward slashes can be used as path separator regardless the operating system. Examples: ```robotframework *** Test Cases *** Import resource Import Resource ${CURDIR}/resource.txt Import Resource ${CURDIR}/../resources/resource.html Import Resource found_from_pythonpath.robot ``` """ try: self._namespace.import_resource(path) except DataError as err: raise RuntimeError(str(err)) def set_library_search_order(self, *search_order: str) -> "tuple[str, ...]": """Sets the resolution order to use when a name matches multiple keywords. Args: search_order: Names defining the search order. Returns: The previous search order. The library search order is used to resolve conflicts when a keyword name that is used matches multiple keyword implementations. The first library (or resource, see below) containing the keyword is selected and that keyword implementation used. If the keyword is not found from any library (or resource), execution fails the same way as when the search order is not set. When this keyword is used, there is no need to use the long `LibraryName.Keyword Name` notation is two or more libraries have a keyword with the same name. ```robotframework *** Test Cases *** No search order MainLibrary.Keyword first usage MainLibrary.Keyword second usage AnotherLibary.Keyword only usage MainLibrary.Keyword third usage Search order set Set Library Search Order MainLibrary Keyword first usage Keyword second usage AnotherLibary.Keyword only usage Keyword third usage ``` This keyword can be used also to set the order of keywords in different resource files. In this case resource names must be given without paths or extensions like: ```robotframework *** Test Cases *** Resource order Set Library Search Order resource another_resource ``` Things to notice about the search order: - The search order is valid only in the suite where this keyword is used. - Keywords in resource files have a higher priority than keywords in libraries regardless the search order. - Library and resource names in the search order are case-insensitive. - Calling this keyword without arguments removes possible search order. """ return self._namespace.set_search_order(search_order) def keyword_should_exist(self, name: KeywordName, msg: "str | None" = None): """Fails unless the given keyword exists in the current scope. Args: name: The keyword to search for. msg: The custom error message. Fails also if there is more than one keyword with the same name. Works both with the short name (e.g. `Log`) and the full name (e.g. `BuiltIn.Log`). """ try: kw = self._namespace.get_runner(name, recommend_on_failure=False).keyword if kw.error: raise DataError(kw.error) except DataError as err: raise AssertionError(msg or err.message) def get_time( self, format: str = "timestamp", time_: "int | float | str | datetime" = "NOW", ) -> "int | str | list[str]": """Returns the given time in the requested format. Args: format: Requested time format. See below for details. time_: Time to use. Defaults to current local time (`NOW`). Returns: The requested time value. > [!TIP] > The [DateTime] library contains much more flexible keywords for > getting the current date and time and for date and time handling in > general. > [!WARNING] > The `time_` argument will be renamed to `time` in Robot Framework 8.0. > Users should avoid using the named argument syntax like `time_=1.5` > and pass the time positionally like `1.5` instead. See issue > [#5762](https://github.com/robotframework/robotframework/issues/5762) > for more information. How time is returned is determined based on the given `format` string as follows. Note that all checks are case-insensitive. 1. If `format` contains the word `epoch`, the time is returned in seconds after the UNIX epoch (1970-01-01 00:00:00 UTC). The return value is always an integer. 2. If `format` contains any of the words `year`, `month`, `day`, `hour`, `min`, or `sec`, only the selected parts are returned. The order of the returned parts is always the one in the previous sentence and the order of words in `format` is not significant. The parts are returned as zero-padded strings (e.g. May -> `05`). 3. Otherwise (and by default) the time is returned as a timestamp string in the format `2006-02-24 15:08:31`. Returns the current local time by default, but that can be altered by using `time` argument as explained below. Note that all checks involving strings are case-insensitive. 1. If `time` is a number, or a string that can be converted to a number, it is interpreted as seconds since the UNIX epoch. This documentation was originally written about 1177654467 seconds after the epoch. 2. If `time` is a timestamp, that time will be used. Valid timestamp formats are `YYYY-MM-DD hh:mm:ss` and `YYYYMMDD hhmmss`. 3. If `time` is equal to `NOW` (default), the current local time is used. 4. If `time` is equal to `UTC`, the current time in [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) is used. 5. If `time` is in the format like `NOW - 1 day` or `UTC + 1 hour 30 min`, the current local/UTC time plus/minus the time specified with the time string is used. The time string format is described in an appendix of Robot Framework User Guide. Examples: ```robotframework *** Test Cases *** Get timestamp ${timestamp} = Get Time Get seconds after epoch ${secs} = Get Time epoch Get time parts ${year} = Get Time year ${yyyy} ${mm} ${dd} = Get Time year, month, day ${year} ${month} = Get Time month and year Custom time ${timestamp} = Get Time timestamp 1177654467 ${tomorrow} = Get Time timestamp NOW + 1 day ``` """ return get_time(format, parse_time(time_)) def evaluate( self, expression: Expression, modules: "str | None" = None, namespace: "Mapping | None" = None, ) -> object: """Evaluates the given expression in Python and returns the result. Args: expression: The expression to evaluate in Python as explained in the [Evaluating expressions] section. modules: A comma separated list of Python modules to be imported and added to the evaluation namespace. namespace: A custom namespace dictionary. Returns: The result of the evaluated expression. Variables used like `${variable}` are replaced in the expression before evaluation. Variables are also available in the evaluation namespace and can be accessed using the special `$variable` syntax as explained in the [Evaluating expressions] section. Modules used in the expression are imported automatically. There are, however, two cases where they need to be explicitly specified using the `modules` argument: - When nested modules like `rootmod.submod` are implemented so that the root module does not automatically import submodules. This is illustrated by the `selenium.webdriver` example below. - When using a module in the expression part of a list comprehension. This is illustrated by the `json` example below. Examples: ```robotframework *** Variables *** ${RC} ${3.14} *** Test Cases *** Normal variables ${status} = Evaluate 0 < ${RC} < 10 Special variable syntax ${status} = Evaluate 0 < $RC < 10 Module auto-imports ${random} = Evaluate random.randint(0, sys.maxsize) Explicit modules ${options} = Evaluate selenium.webdriver.ChromeOptions() modules=selenium.webdriver ${items} = Evaluate [json.loads(item) for item in ('1', '"b"')] modules=json Custom namespace VAR &{ns} x=${4} y=${2} ${result} = Evaluate x*10 + y namespace=${ns} Should Be Equal ${result} 42 type=int ``` """ try: return evaluate_expression( expression, self._variables.current, modules, namespace, ) except DataError as err: raise RuntimeError(err.message) def call_method( self, object: object, method_name: str, *args: object, **kwargs: object, ) -> object: """Calls the named method of the given object with the provided arguments. Args: object: The object whose method to call. method_name: The name of the method to call. *args: Positional arguments passed to the method. **kwargs: Keyword arguments passed to the method. Returns: The return value of the called method. Possible equal signs in `*args` must be escaped with a backslash like `xxx\\=yyy` to avoid them being considered to be part of `**kwargs`. Examples: ```robotframework *** Test Cases *** Call method Call Method ${object} my_method arg1 arg2 Call Method ${object} second_method arg name=value ``` """ try: method = getattr(object, method_name) except AttributeError: raise RuntimeError( f"{type(object).__name__} object does not have method '{method_name}'." ) try: return method(*args, **kwargs) except Exception as err: msg = get_error_message() raise RuntimeError(f"Calling method '{method_name}' failed: {msg}") from err def regexp_escape( self, *strings: "str | bytes" ) -> "str | bytes | list[str | bytes]": """Escape regular expression meta characters in given strings. Args: *strings: The string or strings to escape. Returns: The escaped string, or a list of escaped strings if the keyword was called with multiple strings. This keyword can be used to escape strings so that they can be safely used as part of regular expressions with, for example, [Should Match Regexp] and [Should Not Match Regexp] keywords. Escaping is done with Python's [re.escape()](https://docs.python.org/3/library/re.html#re.escape) function. Examples: ```robotframework *** Test Cases *** Regexp escape ${escaped} = Regexp Escape ${original} @{strings} = Regexp Escape @{strings} ``` """ if len(strings) == 0: return "" if len(strings) == 1: return re.escape(strings[0]) return [re.escape(p) for p in strings] def set_test_message( self, message: str, append: bool = False, separator: str = " ", ): """Sets message of the current test case. Args: message: The message to set. append: If true, the given message is added after the earlier message instead of overwriting it. separator: The separator to use between the old and the new message when appending. In test teardown this keyword can alter the possible failure message, but otherwise failures override messages set by this keyword. Notice that in teardown the message is available as a built-in variable `${TEST MESSAGE}`. It is possible to use HTML format in the message by starting the message with `*HTML*`. Examples: ```robotframework *** Test Cases *** Set test message Set Test Message My message Set Test Message is continued. append=True Should Be Equal ${TEST MESSAGE} My message is continued. Set Test Message *HTML* <b>Hello!</b> ``` This keyword can not be used in suite setup or suite teardown. The `separator` argument is new in Robot Framework 7.2. """ test = self._context.test if not test: raise RuntimeError( "'Set Test Message' keyword cannot be used in suite setup or teardown." ) test.message = self._get_new_text( test.message, message, append, handle_html=True, separator=separator ) if self._context.in_test_teardown: self._variables.set_test("${TEST_MESSAGE}", test.message) message, level = self._get_logged_test_message_and_level(test.message) logger.write(f"Set test message to:\n{message}", level) def _get_new_text(self, old, new, append, handle_html=False, separator=" "): if not isinstance(new, str): new = str(new) if not (append and old): return new if handle_html: if new.startswith("*HTML*"): new = new[6:].lstrip() if not old.startswith("*HTML*"): old = f"*HTML* {html_escape(old)}" separator = html_escape(separator) elif old.startswith("*HTML*"): new = html_escape(new) separator = html_escape(separator) return f"{old}{separator}{new}" def _get_logged_test_message_and_level(self, message): if message.startswith("*HTML*"): return message[6:].lstrip(), "HTML" return message, "INFO" def set_test_documentation( self, doc: str, append: bool = False, separator: str = " ", ): """Sets documentation for the current test case. Args: doc: The documentation to set. append: If true, the given documentation is added after the earlier documentation instead of overwriting it. separator: The separator to use between the old and the new documentation when appending. The current test documentation is available as a built-in variable `${TEST DOCUMENTATION}`. This keyword can not be used in suite setup or suite teardown. The `separator` argument is new in Robot Framework 7.2. """ test = self._context.test if not test: raise RuntimeError( "'Set Test Documentation' keyword cannot be used in " "suite setup or teardown." ) test.doc = self._get_new_text(test.doc, doc, append, separator=separator) self._variables.set_test("${TEST_DOCUMENTATION}", test.doc) logger.info(f"Set test documentation to:\n{test.doc}") def set_test_metadata( self, name: str, value: str, append: bool = False, separator: str = " ", ): """Sets metadata for the current test case. Args: name: The name of the metadata to set. value: The metadata value. append: If true, the given `value` is added after the earlier value instead of overwriting it. separator: The separator to use between the old and the new value when appending. The metadata of the current test is available as a built-in variable `${TEST METADATA}` in a Python dictionary. Notice that modifying this variable directly has no effect on the actual metadata the test has. Metadata names are case, space, and underscore insensitive. This keyword can not be used in suite setup or suite teardown. When creating automated tasks, not tests, it is possible to use [Set Task Metadata]. See also [Set Suite Metadata]. New in Robot Framework 7.5. """ test = self._context.test if not test: raise RuntimeError( "'Set Test Metadata' keyword cannot be used in " "suite setup or teardown." ) if not isinstance(name, str): name = str(name) metadata = test.metadata original = metadata.get(name, "") metadata[name] = self._get_new_text( original, value, append, separator=separator ) self._variables.set_test("${TEST_METADATA}", metadata.copy()) logger.info(f"Set test metadata '{name}' to value '{metadata[name]}'.") def set_task_metadata( self, name: str, value: str, append: bool = False, separator: str = " ", ): """Sets metadata for the current task. Args: name: The name of the metadata to set. value: The metadata value. append: If true, the given `value` is added after the earlier value instead of overwriting it. separator: The separator to use between the old and the new value when appending. This is an alias for [Set Test Metadata] that is more applicable when creating tasks, not tests. New in Robot Framework 7.5. """ self.set_test_metadata(name, value, append, separator) def set_suite_documentation( self, doc: str, append: bool = False, top: bool = False, separator: str = " ", ): """Sets documentation for the current test suite. Args: doc: The documentation to set. append: If true, the given documentation is added after the earlier documentation instead of overwriting it. top: If true, modifies the documentation of the top level suite instead of the current suite. separator: The separator to use between the old and the new documentation when appending. The documentation of the current suite is available as a built-in variable `${SUITE DOCUMENTATION}`. The `separator` argument is new in Robot Framework 7.2. """ suite = self._get_context(top).suite suite.doc = self._get_new_text(suite.doc, doc, append, separator=separator) self._variables.set_suite("${SUITE_DOCUMENTATION}", suite.doc, top) logger.info(f"Set suite documentation to:\n{suite.doc}") def set_suite_metadata( self, name: str, value: str, append: bool = False, top: bool = False, separator: str = " ", ): """Sets metadata for the current test suite. Args: name: The name of the metadata to set. value: The metadata value. append: If true, the given `value` is added after the earlier value instead of overwriting it. top: If true, modifies metadata of the top level suite instead of the current suite. separator: The separator to use between the old and the new value when appending. The metadata of the current suite is available as a built-in variable `${SUITE METADATA}` in a Python dictionary. Notice that modifying this variable directly has no effect on the actual metadata the suite has. See [Set Test Metadata] if you want to set metadata for a single test. The `separator` argument is new in Robot Framework 7.2. """ if not isinstance(name, str): name = str(name) metadata = self._get_context(top).suite.metadata original = metadata.get(name, "") metadata[name] = self._get_new_text( original, value, append, separator=separator ) self._variables.set_suite("${SUITE_METADATA}", metadata.copy(), top) logger.info(f"Set suite metadata '{name}' to value '{metadata[name]}'.") def set_tags(self, *tags: str): """Adds The given `tags` for the current test or all tests in a suite. Args: *tags: The tags to set. When this keyword is used inside a test case, that test gets the specified tags and other tests are not affected. If this keyword is used in a suite setup, all test cases in that suite, recursively, gets the given tags. It is a failure to use this keyword in a suite teardown. The current tags are available as a built-in variable `@{TEST TAGS}`. See [Remove Tags] if you want to remove tags. """ ctx = self._context if ctx.test: ctx.test.tags.add(tags) ctx.variables.set_test("@{TEST_TAGS}", list(ctx.test.tags)) elif not ctx.in_suite_teardown: ctx.suite.set_tags(tags, persist=True) else: raise RuntimeError("'Set Tags' cannot be used in suite teardown.") logger.info(f"Set tag{s(tags)} {seq2str(tags)}.") def remove_tags(self, *tags: str): """Removes given `tags` from the current test or all tests in a suite. Args: tags: The tags to remove. Tags can be given exactly or as [glob patterns] with `*`, `?` and `[chars]` acting as wildcards. This keyword can affect either one test case or all test cases in a test suite similarly as the [Set Tags] keyword. The current tags are available as a built-in variable `@{TEST TAGS}`. """ ctx = self._context if ctx.test: ctx.test.tags.remove(tags) ctx.variables.set_test("@{TEST_TAGS}", list(ctx.test.tags)) elif not ctx.in_suite_teardown: ctx.suite.set_tags(remove=tags, persist=True) else: raise RuntimeError("'Remove Tags' cannot be used in suite teardown.") logger.info(f"Removed tag{s(tags)} {seq2str(tags)}.") def get_library_instance( self, name: "str | None" = None, all: bool = False, ) -> "object | dict[str, object]": """Returns the currently active instance of the specified library. Args: name: The name of the library to get. If the library has been given a custom name using the ´AS` syntax, this name must be the custom name, not the original library name. all: If true, a dictionary mapping all library names to instances is returned Returns: The requested library instance or dictionary of instances. It is possible to use this keyword in the test data and pass the returned library instance to another keyword, but the most important use case is making it possible for libraries to interact with other libraries. That is illustrated by the following example: ```python from robot.libraries.BuiltIn import BuiltIn def title_should_start_with(expected): lib = BuiltIn().get_library_instance('SeleniumLibrary') title = lib.get_title() if not title.startswith(expected): raise AssertionError(f"Title '{title}' did not start with '{expected}'.") ``` """ if all: return self._namespace.get_library_instances() try: return self._namespace.get_library_instance(name) except DataError as err: raise RuntimeError(str(err))
[docs] @library( scope="GLOBAL", version=get_version(), doc_format="MARKDOWN", converters={ KeywordName: lambda value: str(value), KeywordArgument: lambda value: value, Expression: lambda value: value, }, auto_keywords=True, ) class BuiltIn(_Verify, _Converter, _Variables, _RunKeyword, _Control, _Misc): r"""An always available standard library with often needed keywords. `BuiltIn` is Robot Framework's standard library that provides a set of often needed generic keywords. 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% # Controlling failure messages ## Overriding default error message Various validation keywords accept `msg` and `values` arguments that can be used to override keyword specific default failure messages. - If `msg` is given and `values` gets a true value (default), the failure message is `<msg>: <default-message>`. - If `msg` is given and `values` gets a false value, the message is simply `<msg>`. Examples: ```robotframework *** Test Cases *** Default error message [Documentation] Fails with "x != y". Should Be Equal x y Custom error message [Documentation] Fails with "Message: x != y". Should Be Equal x y Message Custom error message without values [Documentation] Fails with "Message". Should Be Equal x y Message values=False ``` ## HTML messages It is possible to use HTML formatting in failure messages by prefixing messages with `*HTML*`. Notice that this is not limited to the BuiltIn library, but works with any error message. Example: ```robotframework *** Test Cases *** HTML message Fail *HTML* <b>Message</b> ``` # String and bytes normalization Various validation keywords accept `ignore_case`, `strip_spaces` and `collapse_spaces` arguments that make it possible to normalize strings and bytes before comparison. They are all `False` by default, which means that no normalization is done, but they can be individually enabled: - If `ignore_case` is given a true value, comparison is case-insensitive. - If `strip_spaces` is given a value `LEADING` or `TRAILING` (case-insensitive), leading or trailing spaces, respectively, are removed before comparison. This includes all white space characters such as newlines and tabs. - If `strip_spaces` is given any other true value, both leading and trailing spaces are removed. - If `collapse_spaces` is given a true value, white space characters are normalized to ASCII spaces and consecutive spaces are collapsed into a single space. If validated items are collections like lists or dictionaries, string and bytes normalization is done recursively. Support for bytes normalization and recursive normalization with collections are new in Robot Framework 7.4. # String representations Several keywords log values and report errors explicitly or implicitly. By default, these messages use human-readable string representation, which means that strings like `Hello` and numbers like `42` are shown 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 [different forms][NFC]. 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 [Python built-in functions](https://docs.python.org/library/functions.html) with same names. More detailed semantics are explained below. ## str Use the human-readable string representation. Equivalent to using [str()](https://docs.python.org/3/library/functions.html#func-str) in Python. This is the default. ## repr Use the machine-readable string representation. Similar to using [repr()](https://docs.python.org/3/library/functions.html#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 collections are pretty-printed so that there is one item per row. ## ascii Same as using [ascii()](https://docs.python.org/3/library/functions.html#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 are not equal but look the same. - Collections are not pretty-printed. # 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](https://docs.python.org/library/functions.html#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: ```robotframework *** Test Cases *** Evaluating expressions 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: ```robotframework *** Test Cases *** Normal variables Should Be True ${rc} < 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: ```robotframework *** Test Cases *** Special variable syntax Should Be True $rc < 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. # 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`: ```robotframework *** Test Cases *** Normal variable syntax Set Suite Variable ${name} value Escaped by removing curly braces Set Suite Variable $name value Escaped with backslash 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`, the earlier examples would have created different variables. 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]. Notice that the [VAR syntax] introduced in Robot Framework 7.0 can be used to create local variables as well as variables in different scopes. It thus unifies creating variables, and it also avoids all the problems discussed above. It is recommended to use that syntax instead of the `Set Global/Suite/Test/Local Variable` keywords whenever possible. # Pattern matching Many keywords accept arguments as either glob or regular expression patterns. ## Glob patterns Some keywords, for example [Should Match], support so called [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming) "Wikipedia") that support the following wildcard characters and character sequences. | Pattern | Explanation | | ---------- | -------------------------------------------------------- | | `*` | 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 matched by the above wildcards. ## Regular expressions Some keywords, for example [Should Match Regexp], support [regular expressions](https://en.wikipedia.org/wiki/Regular_expression "Wikipedia") that are more powerful but also more complicated that glob patterns. The regular expression support is implemented using Python's [re](https://docs.python.org/library/re.html) 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](https://en.wikipedia.org/wiki/Diff_utility#Unified_format "Wikipedia") if both strings have more than two lines. Example: ```robotframework *** Test Cases *** Multiline diff VAR ${first} ... Not in second ... Same ... Differs ... Same ... separator=\n VAR ${second} ... Same ... Differs2 ... Same ... separator=\n Should Be Equal ${first} ${second} ``` Results in the following error message: ``` Multiline strings are different: --- first +++ second @@ -1,4 +1,3 @@ -Not in second Same -Differs +Differs2 Same ``` [DateTime]: https://robotframework.org/robotframework/latest/libraries/DateTime.html [search path]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path [VAR syntax]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#var-syntax [IF/ELSE syntax]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#if-else-syntax [TRY/EXCEPT syntax]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#try-except-syntax [BREAK statement]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#loop-control-using-break-and-continue [CONTINUE statement]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#loop-control-using-break-and-continue [RETURN statement]: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#using-return-statement [NFC]: https://en.wikipedia.org/wiki/Unicode_equivalence """
[docs] class RobotNotRunningError(AttributeError): """Used when something cannot be done because Robot is not running. Based on AttributeError to be backwards compatible with RF < 2.8.5. May later be based directly on Exception, so new code should except this exception explicitly. """
[docs] def register_run_keyword(library, keyword, args_to_process=0, deprecation_warning=True): """Tell Robot Framework that this keyword runs other keywords internally. *NOTE:* This API will change in the future. For more information see https://github.com/robotframework/robotframework/issues/2190. Args: library: Name of the library the keyword belongs to. keyword: Name of the keyword itself. args_to_process: How many arguments to process normally before passing them to the keyword. Other arguments are not touched at all. deprecation_warning: Set to `False` to avoid the warning. Registered keywords are handled specially by Robot so that: - Their arguments are not resolved normally (use `args_to_process` to control that). This basically means not replacing variables or handling escapes. - They are not stopped by timeouts. Prior to Robot Framework 7.3, timeouts occurring when these keywords were executing other keywords could corrupt output files. That bug has been fixed, so this use case why to register keywords as run keyword variants is not relevant anymore. - If there are conflicts with keyword names, these keywords have *lower* precedence than other keywords. Main use cases are: - Library keyword is using `BuiltIn.run_keyword` internally to execute other keywords. Registering the caller as a "run keyword variant" avoids variables and escapes in arguments being resolved multiple times. All arguments passed to `run_keyword` can and should be left unresolved. - Keyword has some need to not resolve variables in arguments. This way variable values are not logged anywhere by Robot automatically. As mentioned above, this API will likely be reimplemented in the future or there could be new API for library keywords to execute other keywords. External libraries can nevertheless use this API if they really need it and are aware of the possible breaking changes in the future. Examples: ```python from robot.libraries.BuiltIn import BuiltIn, register_run_keyword def my_run_keyword(name, *args): # do something return BuiltIn().run_keyword(name, *args) register_run_keyword(__name__, 'My Run Keyword') ``` ```python from robot.libraries.BuiltIn import BuiltIn, register_run_keyword class MyLibrary: def my_run_keyword_if(self, expression, name, *args): # Do something if self._is_true(expression): return BuiltIn().run_keyword(name, *args) # Process one argument normally to get `expression` resolved. register_run_keyword('MyLibrary', 'my_run_keyword_if', args_to_process=1) ``` """ RUN_KW_REGISTER.register_run_keyword( library, keyword, args_to_process, deprecation_warning )