Skip to content

model

Module implementing test execution related model objects.

When tests are executed by Robot Framework, a :class:TestSuite structure using classes defined in this module is created by :class:~robot.running.builder.builders.TestSuiteBuilder based on data on a file system. In addition to that, external tools can create executable suite structures programmatically.

Regardless the approach to construct it, a :class:TestSuite object is executed by calling its :meth:~TestSuite.run method as shown in the example in the :mod:robot.running package level documentation. When a suite is run, test, keywords, and other objects it contains can be inspected and modified by using pre-run modifiers and listeners.

The :class:TestSuite class is exposed via the :mod:robot.api package. If other classes are needed, they can be imported from :mod:robot.running.

__ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#programmatic-modification-of-results __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-interface

Argument

A temporary API for creating named arguments with non-string values.

This class was added in RF 7.0.1 (#5031) after a failed attempt to add a public API for this purpose in RF 7.0 (#5000). A better public API that allows passing named arguments separately was added in RF 7.1 (#5143).

If you need to support also RF 7.0, you can pass named arguments as two-item tuples like (name, value) and positional arguments as one-item tuples like (value,). That approach does not work anymore in RF 7.0.1, though, so the code needs to be conditional depending on Robot Framework version.

The main limitation of this class is that it is not compatible with the JSON model. The current plan is to remove this in the future, possibly already in RF 8.0, but we can consider preserving it if it turns out to be useful.

Source code in src/robot/running/model.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
class Argument:
    """A temporary API for creating named arguments with non-string values.

    This class was added in RF 7.0.1 (#5031) after a failed attempt to add a public
    API for this purpose in RF 7.0 (#5000). A better public API that allows passing
    named arguments separately was added in RF 7.1 (#5143).

    If you need to support also RF 7.0, you can pass named arguments as two-item tuples
    like `(name, value)` and positional arguments as one-item tuples like `(value,)`.
    That approach does not work anymore in RF 7.0.1, though, so the code needs to be
    conditional depending on Robot Framework version.

    The main limitation of this class is that it is not compatible with the JSON model.
    The current plan is to remove this in the future, possibly already in RF 8.0, but
    we can consider preserving it if it turns out to be useful.
    """

    def __init__(self, name: 'str|None', value: Any):
        """
        :param name: Argument name. If ``None``, argument is considered positional.
        :param value: Argument value.
        """
        self.name = name
        self.value = value

    def __str__(self):
        return str(self.value) if self.name is None else f'{self.name}={self.value}'

__init__(name, value)

:param name: Argument name. If None, argument is considered positional. :param value: Argument value.

Source code in src/robot/running/model.py 
100
101
102
103
104
105
106
def __init__(self, name: 'str|None', value: Any):
    """
    :param name: Argument name. If ``None``, argument is considered positional.
    :param value: Argument value.
    """
    self.name = name
    self.value = value

Keyword

Bases: Keyword, WithSource

Represents an executable keyword call.

A keyword call consists only of a keyword name, arguments and possible assignment in the data::

1
2
Keyword    arg
${result} =    Another Keyword    arg1    arg2

The actual keyword that is executed depends on the context where this model is executed.

Arguments originating from normal Robot Framework data are stored in the :attr:args attribute as a tuple of strings in the exact same format as in the data. This means that arguments can have variables and escape characters, and that named arguments are specified using the name=value syntax.

When creating keywords programmatically, it is possible to set :attr:named_args separately and use :attr:args only for positional arguments. Argument values do not need to be strings, but also in this case strings can contain variables and normal Robot Framework escaping rules must be taken into account.

Source code in src/robot/running/model.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@Body.register
class Keyword(model.Keyword, WithSource):
    """Represents an executable keyword call.

    A keyword call consists only of a keyword name, arguments and possible
    assignment in the data::

        Keyword    arg
        ${result} =    Another Keyword    arg1    arg2

    The actual keyword that is executed depends on the context where this model
    is executed.

    Arguments originating from normal Robot Framework data are stored in the
    :attr:`args` attribute as a tuple of strings in the exact same format as in
    the data. This means that arguments can have variables and escape characters,
    and that named arguments are specified using the ``name=value`` syntax.

    When creating keywords programmatically, it is possible to set :attr:`named_args`
    separately and use :attr:`args` only for positional arguments. Argument values
    do not need to be strings, but also in this case strings can contain variables
    and normal Robot Framework escaping rules must be taken into account.
    """
    __slots__ = ['named_args', 'lineno']

    def __init__(self, name: str = '',
                 args: 'Sequence[str|Argument|Any]' = (),
                 named_args: 'Mapping[str, Any]|None' = None,
                 assign: Sequence[str] = (),
                 type: str = BodyItem.KEYWORD,
                 parent: BodyItemParent = None,
                 lineno: 'int|None' = None):
        super().__init__(name, args, assign, type, parent)
        self.named_args = named_args
        self.lineno = lineno

    def to_dict(self) -> DataDict:
        data = super().to_dict()
        if self.named_args is not None:
            data['named_args'] = self.named_args
        if self.lineno:
            data['lineno'] = self.lineno
        return data

    def run(self, result, context, run=True, templated=None):
        return KeywordRunner(context, run).run(self, result.body.create_keyword())

config(**attributes)

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

Source code in src/robot/model/modelobject.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def config(self: T, **attributes) -> T:
    """Configure model object with given attributes.

    ``obj.config(name='Example', doc='Something')`` is equivalent to setting
    ``obj.name = 'Example'`` and ``obj.doc = 'Something'``.

    New in Robot Framework 4.0.
    """
    for name, value in attributes.items():
        try:
            orig = getattr(self, name)
        except AttributeError:
            raise AttributeError(f"'{full_name(self)}' object does not have "
                                 f"attribute '{name}'")
        # Preserve tuples. Main motivation is converting lists with `from_json`.
        if isinstance(orig, tuple) and not isinstance(value, tuple):
            try:
                value = tuple(value)
            except TypeError:
                raise TypeError(f"'{full_name(self)}' object attribute '{name}' "
                                f"is 'tuple', got '{type_name(value)}'.")
        try:
            setattr(self, name, value)
        except AttributeError as err:
            # Ignore error setting attribute if the object already has it.
            # Avoids problems with `from_dict` with body items having
            # un-settable `type` attribute that is needed in dict data.
            if value != orig:
                raise AttributeError(f"Setting attribute '{name}' failed: {err}")
    return self

copy(**attributes)

Return a shallow copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also :meth:deepcopy. The difference between copy and deepcopy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
def copy(self: T, **attributes) -> T:
    """Return a shallow copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.copy(name='New name')``.

    See also :meth:`deepcopy`. The difference between ``copy`` and
    ``deepcopy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.copy(self).config(**attributes)

deepcopy(**attributes)

Return a deep copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.deepcopy(name='New name').

See also :meth:copy. The difference between deepcopy and copy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
def deepcopy(self: T, **attributes) -> T:
    """Return a deep copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.deepcopy(name='New name')``.

    See also :meth:`copy`. The difference between ``deepcopy`` and
    ``copy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.deepcopy(self).config(**attributes)

from_dict(data) classmethod

Create this object based on data in a dictionary.

Data can be got from the :meth:to_dict method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@classmethod
def from_dict(cls: Type[T], data: DataDict) -> T:
    """Create this object based on data in a dictionary.

    Data can be got from the :meth:`to_dict` method or created externally.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        return cls().config(**data)
    except (AttributeError, TypeError) as err:
        raise DataError(f"Creating '{full_name(cls)}' object from dictionary "
                        f"failed: {err}")

from_json(source) classmethod

Create this object based on JSON data.

The data is given as the source parameter. It can be:

  • a string (or bytes) containing the data directly,
  • an open file object where to read the data from, or
  • a path (pathlib.Path or string) to a UTF-8 encoded file to read.

The JSON data is first converted to a Python dictionary and the object created using the :meth:from_dict method.

Notice that the source is considered to be JSON data if it is a string and contains {. If you need to use { in a file system path, pass it in as a pathlib.Path instance.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def from_json(cls: Type[T], source: 'str|bytes|TextIO|Path') -> T:
    """Create this object based on JSON data.

    The data is given as the ``source`` parameter. It can be:

    - a string (or bytes) containing the data directly,
    - an open file object where to read the data from, or
    - a path (``pathlib.Path`` or string) to a UTF-8 encoded file to read.

    The JSON data is first converted to a Python dictionary and the object
    created using the :meth:`from_dict` method.

    Notice that the ``source`` is considered to be JSON data if it is
    a string and contains ``{``. If you need to use ``{`` in a file system
    path, pass it in as a ``pathlib.Path`` instance.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        data = JsonLoader().load(source)
    except (TypeError, ValueError) as err:
        raise DataError(f'Loading JSON data failed: {err}')
    return cls.from_dict(data)

to_json(file=None, *, ensure_ascii=False, indent=0, separators=(',', ':'))

Serialize this object into JSON.

The object is first converted to a Python dictionary using the :meth:to_dict method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data to, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json__ module. Notice that the defaults differ from what json uses.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

__ https://docs.python.org/3/library/json.html

Source code in src/robot/model/modelobject.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def to_json(self, file: 'None|TextIO|Path|str' = None, *,
            ensure_ascii: bool = False, indent: int = 0,
            separators: 'tuple[str, str]' = (',', ':')) -> 'str|None':
    """Serialize this object into JSON.

    The object is first converted to a Python dictionary using the
    :meth:`to_dict` method and then the dictionary is converted to JSON.

    The ``file`` parameter controls what to do with the resulting JSON data.
    It can be:

    - ``None`` (default) to return the data as a string,
    - an open file object where to write the data to, or
    - a path (``pathlib.Path`` or string) to a file where to write
      the data using UTF-8 encoding.

    JSON formatting can be configured using optional parameters that
    are passed directly to the underlying json__ module. Notice that
    the defaults differ from what ``json`` uses.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.

    __ https://docs.python.org/3/library/json.html
    """
    return JsonDumper(ensure_ascii=ensure_ascii, indent=indent,
                      separators=separators).dump(self.to_dict(), file)

visit(visitor)

:mod:Visitor interface <robot.model.visitor> entry-point.

Source code in src/robot/model/keyword.py 
52
53
54
55
def visit(self, visitor: 'SuiteVisitor'):
    """:mod:`Visitor interface <robot.model.visitor>` entry-point."""
    if self:
        visitor.visit_keyword(self)

TestCase

Bases: TestCase[Keyword]

Represents a single executable test case.

See the base class for documentation of attributes not documented here.

Source code in src/robot/running/model.py 
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
class TestCase(model.TestCase[Keyword]):
    """Represents a single executable test case.

    See the base class for documentation of attributes not documented here.
    """
    __slots__ = ['template', 'error']
    body_class = Body        #: Internal usage only.
    fixture_class = Keyword  #: Internal usage only.

    def __init__(self, name: str = '',
                 doc: str = '',
                 tags: Sequence[str] = (),
                 timeout: 'str|None' = None,
                 lineno: 'int|None' = None,
                 parent: 'TestSuite|None' = None,
                 template: 'str|None' = None,
                 error: 'str|None' = None):
        super().__init__(name, doc, tags, timeout, lineno, parent)
        #: Name of the keyword that has been used as a template when building the test.
        # ``None`` if template is not used.
        self.template = template
        self.error = error

    def to_dict(self) -> DataDict:
        data = super().to_dict()
        if self.template:
            data['template'] = self.template
        if self.error:
            data['error'] = self.error
        return data

    @setter
    def body(self, body: 'Sequence[BodyItem|DataDict]') -> Body:
        """Test body as a :class:`~robot.running.Body` object."""
        return self.body_class(self, body)

full_name: str property

Test name prefixed with the full name of the parent suite.

has_setup: bool property

Check does a suite have a setup without creating a setup object.

A difference between using if test.has_setup: and if test.setup: is that accessing the :attr:setup attribute creates a :class:Keyword object representing the setup even when the test actually does not have one. This typically does not matter, but with bigger suite structures containing a huge about of tests it can have an effect on memory usage.

New in Robot Framework 5.0.

has_teardown: bool property

Check does a test have a teardown without creating a teardown object.

See :attr:has_setup for more information.

New in Robot Framework 5.0.

id: str property

Test case id in format like s1-t3.

See :attr:TestSuite.id <robot.model.testsuite.TestSuite.id> for more information.

longname: str property

Deprecated since Robot Framework 7.0. Use :attr:full_name instead.

setup: KW property writable

Test setup as a :class:~.model.keyword.Keyword object.

This attribute is a Keyword object also when a test has no setup but in that case its truth value is False.

Setup can be modified by setting attributes directly::

1
2
test.setup.name = 'Example'
test.setup.args = ('First', 'Second')

Alternatively the :meth:config method can be used to set multiple attributes in one call::

1
test.setup.config(name='Example', args=('First', 'Second'))

The easiest way to reset the whole setup is setting it to None. It will automatically recreate the underlying Keyword object::

1
test.setup = None

New in Robot Framework 4.0. Earlier setup was accessed like test.keywords.setup.

teardown: KW property writable

Test teardown as a :class:~.model.keyword.Keyword object.

See :attr:setup for more information.

body(body)

Test body as a :class:~robot.running.Body object.

Source code in src/robot/running/model.py 
565
566
567
568
@setter
def body(self, body: 'Sequence[BodyItem|DataDict]') -> Body:
    """Test body as a :class:`~robot.running.Body` object."""
    return self.body_class(self, body)

config(**attributes)

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

Source code in src/robot/model/modelobject.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def config(self: T, **attributes) -> T:
    """Configure model object with given attributes.

    ``obj.config(name='Example', doc='Something')`` is equivalent to setting
    ``obj.name = 'Example'`` and ``obj.doc = 'Something'``.

    New in Robot Framework 4.0.
    """
    for name, value in attributes.items():
        try:
            orig = getattr(self, name)
        except AttributeError:
            raise AttributeError(f"'{full_name(self)}' object does not have "
                                 f"attribute '{name}'")
        # Preserve tuples. Main motivation is converting lists with `from_json`.
        if isinstance(orig, tuple) and not isinstance(value, tuple):
            try:
                value = tuple(value)
            except TypeError:
                raise TypeError(f"'{full_name(self)}' object attribute '{name}' "
                                f"is 'tuple', got '{type_name(value)}'.")
        try:
            setattr(self, name, value)
        except AttributeError as err:
            # Ignore error setting attribute if the object already has it.
            # Avoids problems with `from_dict` with body items having
            # un-settable `type` attribute that is needed in dict data.
            if value != orig:
                raise AttributeError(f"Setting attribute '{name}' failed: {err}")
    return self

copy(**attributes)

Return a shallow copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also :meth:deepcopy. The difference between copy and deepcopy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
def copy(self: T, **attributes) -> T:
    """Return a shallow copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.copy(name='New name')``.

    See also :meth:`deepcopy`. The difference between ``copy`` and
    ``deepcopy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.copy(self).config(**attributes)

deepcopy(**attributes)

Return a deep copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.deepcopy(name='New name').

See also :meth:copy. The difference between deepcopy and copy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
def deepcopy(self: T, **attributes) -> T:
    """Return a deep copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.deepcopy(name='New name')``.

    See also :meth:`copy`. The difference between ``deepcopy`` and
    ``copy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.deepcopy(self).config(**attributes)

from_dict(data) classmethod

Create this object based on data in a dictionary.

Data can be got from the :meth:to_dict method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@classmethod
def from_dict(cls: Type[T], data: DataDict) -> T:
    """Create this object based on data in a dictionary.

    Data can be got from the :meth:`to_dict` method or created externally.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        return cls().config(**data)
    except (AttributeError, TypeError) as err:
        raise DataError(f"Creating '{full_name(cls)}' object from dictionary "
                        f"failed: {err}")

from_json(source) classmethod

Create this object based on JSON data.

The data is given as the source parameter. It can be:

  • a string (or bytes) containing the data directly,
  • an open file object where to read the data from, or
  • a path (pathlib.Path or string) to a UTF-8 encoded file to read.

The JSON data is first converted to a Python dictionary and the object created using the :meth:from_dict method.

Notice that the source is considered to be JSON data if it is a string and contains {. If you need to use { in a file system path, pass it in as a pathlib.Path instance.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def from_json(cls: Type[T], source: 'str|bytes|TextIO|Path') -> T:
    """Create this object based on JSON data.

    The data is given as the ``source`` parameter. It can be:

    - a string (or bytes) containing the data directly,
    - an open file object where to read the data from, or
    - a path (``pathlib.Path`` or string) to a UTF-8 encoded file to read.

    The JSON data is first converted to a Python dictionary and the object
    created using the :meth:`from_dict` method.

    Notice that the ``source`` is considered to be JSON data if it is
    a string and contains ``{``. If you need to use ``{`` in a file system
    path, pass it in as a ``pathlib.Path`` instance.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        data = JsonLoader().load(source)
    except (TypeError, ValueError) as err:
        raise DataError(f'Loading JSON data failed: {err}')
    return cls.from_dict(data)

tags(tags)

Test tags as a :class:~.model.tags.Tags object.

Source code in src/robot/model/testcase.py 
70
71
72
73
@setter
def tags(self, tags: 'Tags|Sequence[str]') -> Tags:
    """Test tags as a :class:`~.model.tags.Tags` object."""
    return Tags(tags)

to_json(file=None, *, ensure_ascii=False, indent=0, separators=(',', ':'))

Serialize this object into JSON.

The object is first converted to a Python dictionary using the :meth:to_dict method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data to, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json__ module. Notice that the defaults differ from what json uses.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

__ https://docs.python.org/3/library/json.html

Source code in src/robot/model/modelobject.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def to_json(self, file: 'None|TextIO|Path|str' = None, *,
            ensure_ascii: bool = False, indent: int = 0,
            separators: 'tuple[str, str]' = (',', ':')) -> 'str|None':
    """Serialize this object into JSON.

    The object is first converted to a Python dictionary using the
    :meth:`to_dict` method and then the dictionary is converted to JSON.

    The ``file`` parameter controls what to do with the resulting JSON data.
    It can be:

    - ``None`` (default) to return the data as a string,
    - an open file object where to write the data to, or
    - a path (``pathlib.Path`` or string) to a file where to write
      the data using UTF-8 encoding.

    JSON formatting can be configured using optional parameters that
    are passed directly to the underlying json__ module. Notice that
    the defaults differ from what ``json`` uses.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.

    __ https://docs.python.org/3/library/json.html
    """
    return JsonDumper(ensure_ascii=ensure_ascii, indent=indent,
                      separators=separators).dump(self.to_dict(), file)

visit(visitor)

:mod:Visitor interface <robot.model.visitor> entry-point.

Source code in src/robot/model/testcase.py 
175
176
177
def visit(self, visitor: 'SuiteVisitor'):
    """:mod:`Visitor interface <robot.model.visitor>` entry-point."""
    visitor.visit_test(self)

TestSuite

Bases: TestSuite[Keyword, TestCase]

Represents a single executable test suite.

See the base class for documentation of attributes not documented here.

Source code in src/robot/running/model.py 
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
class TestSuite(model.TestSuite[Keyword, TestCase]):
    """Represents a single executable test suite.

    See the base class for documentation of attributes not documented here.
    """
    __slots__ = []
    test_class = TestCase    #: Internal usage only.
    fixture_class = Keyword  #: Internal usage only.

    def __init__(self, name: str = '',
                 doc: str = '',
                 metadata: 'Mapping[str, str]|None' = None,
                 source: 'Path|str|None' = None,
                 rpa: 'bool|None' = False,
                 parent: 'TestSuite|None' = None):
        super().__init__(name, doc, metadata, source, rpa, parent)
        #: :class:`ResourceFile` instance containing imports, variables and
        #: keywords the suite owns. When data is parsed from the file system,
        #: this data comes from the same test case file that creates the suite.
        self.resource = None

    @setter
    def resource(self, resource: 'ResourceFile|dict|None') -> 'ResourceFile':
        from .resourcemodel import ResourceFile

        if resource is None:
            resource = ResourceFile()
        if isinstance(resource, dict):
            resource = ResourceFile.from_dict(resource)
        resource.owner = self
        return resource

    @classmethod
    def from_file_system(cls, *paths: 'Path|str', **config) -> 'TestSuite':
        """Create a :class:`TestSuite` object based on the given ``paths``.

        :param paths: File or directory paths where to read the data from.
        :param config: Configuration parameters for :class:`~.builders.TestSuiteBuilder`
            class that is used internally for building the suite.

        See also :meth:`from_model` and :meth:`from_string`.
        """
        from .builder import TestSuiteBuilder
        return TestSuiteBuilder(**config).build(*paths)

    @classmethod
    def from_model(cls, model: 'File', name: 'str|None' = None, *,
                   defaults: 'TestDefaults|None' = None) -> 'TestSuite':
        """Create a :class:`TestSuite` object based on the given ``model``.

        :param model: Model to create the suite from.
        :param name: Deprecated since Robot Framework 6.1.
        :param defaults: Possible test specific defaults from suite
            initialization files. New in Robot Framework 6.1.

        The model can be created by using the
        :func:`~robot.parsing.parser.parser.get_model` function and possibly
        modified by other tooling in the :mod:`robot.parsing` module.

        Giving suite name is deprecated and users should set it and possible
        other attributes to the returned suite separately. One easy way is using
        the :meth:`config` method like this::

            suite = TestSuite.from_model(model).config(name='X', doc='Example')

        See also :meth:`from_file_system` and :meth:`from_string`.
        """
        from .builder import RobotParser
        suite = RobotParser().parse_model(model, defaults)
        if name is not None:
            # TODO: Remove 'name' in RF 7.
            warnings.warn("'name' argument of 'TestSuite.from_model' is deprecated. "
                          "Set the name to the returned suite separately.")
            suite.name = name
        return suite

    @classmethod
    def from_string(cls, string: str, *, defaults: 'TestDefaults|None' = None,
                    **config) -> 'TestSuite':
        """Create a :class:`TestSuite` object based on the given ``string``.

        :param string: String to create the suite from.
        :param defaults: Possible test specific defaults from suite
            initialization files.
        :param config: Configuration parameters for
             :func:`~robot.parsing.parser.parser.get_model` used internally.

        If suite name or other attributes need to be set, an easy way is using
        the :meth:`config` method like this::

            suite = TestSuite.from_string(string).config(name='X', doc='Example')

        New in Robot Framework 6.1. See also :meth:`from_model` and
        :meth:`from_file_system`.
        """
        from robot.parsing import get_model
        model = get_model(string, data_only=True, **config)
        return cls.from_model(model, defaults=defaults)

    def configure(self, randomize_suites: bool = False, randomize_tests: bool = False,
                  randomize_seed: 'int|None' = None, **options):
        """A shortcut to configure a suite using one method call.

        Can only be used with the root test suite.

        :param randomize_xxx: Passed to :meth:`randomize`.
        :param options: Passed to
            :class:`~robot.model.configurer.SuiteConfigurer` that will then
            set suite attributes, call :meth:`filter`, etc. as needed.

        Example::

            suite.configure(include_tags=['smoke'],
                            doc='Smoke test results.')

        Not to be confused with :meth:`config` method that suites, tests,
        and keywords have to make it possible to set multiple attributes in
        one call.
        """
        super().configure(**options)
        self.randomize(randomize_suites, randomize_tests, randomize_seed)

    def randomize(self, suites: bool = True, tests: bool = True,
                  seed: 'int|None' = None):
        """Randomizes the order of suites and/or tests, recursively.

        :param suites: Boolean controlling should suites be randomized.
        :param tests: Boolean controlling should tests be randomized.
        :param seed: Random seed. Can be given if previous random order needs
            to be re-created. Seed value is always shown in logs and reports.
        """
        self.visit(Randomizer(suites, tests, seed))

    @setter
    def suites(self, suites: 'Sequence[TestSuite|DataDict]') -> TestSuites['TestSuite']:
        return TestSuites['TestSuite'](self.__class__, self, suites)

    def run(self, settings=None, **options):
        """Executes the suite based on the given ``settings`` or ``options``.

        :param settings: :class:`~robot.conf.settings.RobotSettings` object
            to configure test execution.
        :param options: Used to construct new
            :class:`~robot.conf.settings.RobotSettings` object if ``settings``
            are not given.
        :return: :class:`~robot.result.executionresult.Result` object with
            information about executed suites and tests.

        If ``options`` are used, their names are the same as long command line
        options except without hyphens. Some options are ignored (see below),
        but otherwise they have the same semantics as on the command line.
        Options that can be given on the command line multiple times can be
        passed as lists like ``variable=['VAR1:value1', 'VAR2:value2']``.
        If such an option is used only once, it can be given also as a single
        string like ``variable='VAR:value'``.

        Additionally, listener option allows passing object directly instead of
        listener name, e.g. ``run('tests.robot', listener=Listener())``.

        To capture stdout and/or stderr streams, pass open file objects in as
        special keyword arguments ``stdout`` and ``stderr``, respectively.

        Only options related to the actual test execution have an effect.
        For example, options related to selecting or modifying test cases or
        suites (e.g. ``--include``, ``--name``, ``--prerunmodifier``) or
        creating logs and reports are silently ignored. The output XML
        generated as part of the execution can be configured, though. This
        includes disabling it with ``output=None``.

        Example::

            stdout = StringIO()
            result = suite.run(variable='EXAMPLE:value',
                               output='example.xml',
                               exitonfailure=True,
                               stdout=stdout)
            print(result.return_code)

        To save memory, the returned
        :class:`~robot.result.executionresult.Result` object does not
        have any information about the executed keywords. If that information
        is needed, the created output XML file needs to be read  using the
        :class:`~robot.result.resultbuilder.ExecutionResult` factory method.

        See the :mod:`package level <robot.running>` documentation for
        more examples, including how to construct executable test suites and
        how to create logs and reports based on the execution results.

        See the :func:`robot.run <robot.run.run>` function for a higher-level
        API for executing tests in files or directories.
        """
        from .namespace import IMPORTER
        from .signalhandler import STOP_SIGNAL_MONITOR
        from .suiterunner import SuiteRunner

        with LOGGER:
            if not settings:
                settings = RobotSettings(options)
                LOGGER.register_console_logger(**settings.console_output_config)
            with pyloggingconf.robot_handler_enabled(settings.log_level):
                with STOP_SIGNAL_MONITOR:
                    IMPORTER.reset()
                    output = Output(settings)
                    runner = SuiteRunner(output, settings)
                    self.visit(runner)
                output.close(runner.result)
        return runner.result

    def to_dict(self) -> DataDict:
        data = super().to_dict()
        data['resource'] = self.resource.to_dict()
        return data

all_tests: Iterator[TestCase] property

Yields all tests this suite and its child suites contain.

New in Robot Framework 6.1.

full_name: str property

Suite name prefixed with the full name of the possible parent suite.

Just :attr:name of the suite if it has no :attr:parent.

has_setup: bool property

Check does a suite have a setup without creating a setup object.

A difference between using if suite.has_setup: and if suite.setup: is that accessing the :attr:setup attribute creates a :class:Keyword object representing the setup even when the suite actually does not have one. This typically does not matter, but with bigger suite structures it can have some effect on memory usage.

New in Robot Framework 5.0.

has_teardown: bool property

Check does a suite have a teardown without creating a teardown object.

See :attr:has_setup for more information.

New in Robot Framework 5.0.

id: str property

An automatically generated unique id.

The root suite has id s1, its child suites have ids s1-s1, s1-s2, ..., their child suites get ids s1-s1-s1, s1-s1-s2, ..., s1-s2-s1, ..., and so on.

The first test in a suite has an id like s1-t1, the second has an id s1-t2, and so on. Similarly, keywords in suites (setup/teardown) and in tests get ids like s1-k1, s1-t1-k1, and s1-s4-t2-k5.

longname: str property

Deprecated since Robot Framework 7.0. Use :attr:full_name instead.

name: str property writable

Suite name.

If name is not set, it is constructed from source. If source is not set, name is constructed from child suite names by concatenating them with &. If there are no child suites, name is an empty string.

setup: KW property writable

Suite setup.

This attribute is a Keyword object also when a suite has no setup but in that case its truth value is False. The preferred way to check does a suite have a setup is using :attr:has_setup.

Setup can be modified by setting attributes directly::

1
2
suite.setup.name = 'Example'
suite.setup.args = ('First', 'Second')

Alternatively the :meth:config method can be used to set multiple attributes in one call::

1
suite.setup.config(name='Example', args=('First', 'Second'))

The easiest way to reset the whole setup is setting it to None. It will automatically recreate the underlying Keyword object::

1
suite.setup = None

New in Robot Framework 4.0. Earlier setup was accessed like suite.keywords.setup.

teardown: KW property writable

Suite teardown.

See :attr:setup for more information.

test_count: int property

Total number of the tests in this suite and in its child suites.

adjust_source(relative_to=None, root=None)

Adjust suite source and child suite sources, recursively.

:param relative_to: Make suite source relative to the given path. Calls pathlib.Path.relative_to()__ internally. Raises ValueError if creating a relative path is not possible. :param root: Make given path a new root directory for the source. Raises ValueError if suite source is absolute.

Adjusting the source is especially useful when moving data around as JSON::

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from robot.api import TestSuite

# Create a suite, adjust source and convert to JSON.
suite = TestSuite.from_file_system('/path/to/data')
suite.adjust_source(relative_to='/path/to')
suite.to_json('data.rbt')

# Recreate suite elsewhere and adjust source accordingly.
suite = TestSuite.from_json('data.rbt')
suite.adjust_source(root='/new/path/to')

New in Robot Framework 6.1.

__ https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.relative_to

Source code in src/robot/model/testsuite.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def adjust_source(self, relative_to: 'Path|str|None' = None,
                  root: 'Path|str|None' = None):
    """Adjust suite source and child suite sources, recursively.

    :param relative_to: Make suite source relative to the given path. Calls
        `pathlib.Path.relative_to()`__ internally. Raises ``ValueError``
        if creating a relative path is not possible.
    :param root: Make given path a new root directory for the source. Raises
        ``ValueError`` if suite source is absolute.

    Adjusting the source is especially useful when moving data around as JSON::

        from robot.api import TestSuite

        # Create a suite, adjust source and convert to JSON.
        suite = TestSuite.from_file_system('/path/to/data')
        suite.adjust_source(relative_to='/path/to')
        suite.to_json('data.rbt')

        # Recreate suite elsewhere and adjust source accordingly.
        suite = TestSuite.from_json('data.rbt')
        suite.adjust_source(root='/new/path/to')

    New in Robot Framework 6.1.

    __ https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.relative_to
    """
    if not self.source:
        raise ValueError('Suite has no source.')
    if relative_to:
        self.source = self.source.relative_to(relative_to)
    if root:
        if self.source.is_absolute():
            raise ValueError(f"Cannot set root for absolute source '{self.source}'.")
        self.source = root / self.source
    for suite in self.suites:
        suite.adjust_source(relative_to, root)

config(**attributes)

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

Source code in src/robot/model/modelobject.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def config(self: T, **attributes) -> T:
    """Configure model object with given attributes.

    ``obj.config(name='Example', doc='Something')`` is equivalent to setting
    ``obj.name = 'Example'`` and ``obj.doc = 'Something'``.

    New in Robot Framework 4.0.
    """
    for name, value in attributes.items():
        try:
            orig = getattr(self, name)
        except AttributeError:
            raise AttributeError(f"'{full_name(self)}' object does not have "
                                 f"attribute '{name}'")
        # Preserve tuples. Main motivation is converting lists with `from_json`.
        if isinstance(orig, tuple) and not isinstance(value, tuple):
            try:
                value = tuple(value)
            except TypeError:
                raise TypeError(f"'{full_name(self)}' object attribute '{name}' "
                                f"is 'tuple', got '{type_name(value)}'.")
        try:
            setattr(self, name, value)
        except AttributeError as err:
            # Ignore error setting attribute if the object already has it.
            # Avoids problems with `from_dict` with body items having
            # un-settable `type` attribute that is needed in dict data.
            if value != orig:
                raise AttributeError(f"Setting attribute '{name}' failed: {err}")
    return self

configure(randomize_suites=False, randomize_tests=False, randomize_seed=None, **options)

A shortcut to configure a suite using one method call.

Can only be used with the root test suite.

:param randomize_xxx: Passed to :meth:randomize. :param options: Passed to :class:~robot.model.configurer.SuiteConfigurer that will then set suite attributes, call :meth:filter, etc. as needed.

Example::

1
2
suite.configure(include_tags=['smoke'],
                doc='Smoke test results.')

Not to be confused with :meth:config method that suites, tests, and keywords have to make it possible to set multiple attributes in one call.

Source code in src/robot/running/model.py 
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
def configure(self, randomize_suites: bool = False, randomize_tests: bool = False,
              randomize_seed: 'int|None' = None, **options):
    """A shortcut to configure a suite using one method call.

    Can only be used with the root test suite.

    :param randomize_xxx: Passed to :meth:`randomize`.
    :param options: Passed to
        :class:`~robot.model.configurer.SuiteConfigurer` that will then
        set suite attributes, call :meth:`filter`, etc. as needed.

    Example::

        suite.configure(include_tags=['smoke'],
                        doc='Smoke test results.')

    Not to be confused with :meth:`config` method that suites, tests,
    and keywords have to make it possible to set multiple attributes in
    one call.
    """
    super().configure(**options)
    self.randomize(randomize_suites, randomize_tests, randomize_seed)

copy(**attributes)

Return a shallow copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also :meth:deepcopy. The difference between copy and deepcopy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
def copy(self: T, **attributes) -> T:
    """Return a shallow copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.copy(name='New name')``.

    See also :meth:`deepcopy`. The difference between ``copy`` and
    ``deepcopy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.copy(self).config(**attributes)

deepcopy(**attributes)

Return a deep copy of this object.

:param attributes: Attributes to be set to the returned copy. For example, obj.deepcopy(name='New name').

See also :meth:copy. The difference between deepcopy and copy is the same as with the methods having same names in the copy__ module.

__ https://docs.python.org/3/library/copy.html

Source code in src/robot/model/modelobject.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
def deepcopy(self: T, **attributes) -> T:
    """Return a deep copy of this object.

    :param attributes: Attributes to be set to the returned copy.
        For example, ``obj.deepcopy(name='New name')``.

    See also :meth:`copy`. The difference between ``deepcopy`` and
    ``copy`` is the same as with the methods having same names in
    the copy__ module.

    __ https://docs.python.org/3/library/copy.html
    """
    return copy.deepcopy(self).config(**attributes)

filter(included_suites=None, included_tests=None, included_tags=None, excluded_tags=None)

Select test cases and remove others from this suite.

Parameters have the same semantics as --suite, --test, --include, and --exclude command line options. All of them can be given as a list of strings, or when selecting only one, as a single string.

Child suites that contain no tests after filtering are automatically removed.

Example::

1
2
suite.filter(included_tests=['Test 1', '* Example'],
             included_tags='priority-1')
Source code in src/robot/model/testsuite.py 
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
def filter(self, included_suites: 'Sequence[str]|None' = None,
           included_tests: 'Sequence[str]|None' = None,
           included_tags: 'Sequence[str]|None' = None,
           excluded_tags: 'Sequence[str]|None' = None):
    """Select test cases and remove others from this suite.

    Parameters have the same semantics as ``--suite``, ``--test``,
    ``--include``, and ``--exclude`` command line options. All of them
    can be given as a list of strings, or when selecting only one, as
    a single string.

    Child suites that contain no tests after filtering are automatically
    removed.

    Example::

        suite.filter(included_tests=['Test 1', '* Example'],
                     included_tags='priority-1')
    """
    self.visit(Filter(included_suites, included_tests,
                      included_tags, excluded_tags))

from_dict(data) classmethod

Create this object based on data in a dictionary.

Data can be got from the :meth:to_dict method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@classmethod
def from_dict(cls: Type[T], data: DataDict) -> T:
    """Create this object based on data in a dictionary.

    Data can be got from the :meth:`to_dict` method or created externally.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        return cls().config(**data)
    except (AttributeError, TypeError) as err:
        raise DataError(f"Creating '{full_name(cls)}' object from dictionary "
                        f"failed: {err}")

from_file_system(*paths, **config) classmethod

Create a :class:TestSuite object based on the given paths.

:param paths: File or directory paths where to read the data from. :param config: Configuration parameters for :class:~.builders.TestSuiteBuilder class that is used internally for building the suite.

See also :meth:from_model and :meth:from_string.

Source code in src/robot/running/model.py 
603
604
605
606
607
608
609
610
611
612
613
614
@classmethod
def from_file_system(cls, *paths: 'Path|str', **config) -> 'TestSuite':
    """Create a :class:`TestSuite` object based on the given ``paths``.

    :param paths: File or directory paths where to read the data from.
    :param config: Configuration parameters for :class:`~.builders.TestSuiteBuilder`
        class that is used internally for building the suite.

    See also :meth:`from_model` and :meth:`from_string`.
    """
    from .builder import TestSuiteBuilder
    return TestSuiteBuilder(**config).build(*paths)

from_json(source) classmethod

Create this object based on JSON data.

The data is given as the source parameter. It can be:

  • a string (or bytes) containing the data directly,
  • an open file object where to read the data from, or
  • a path (pathlib.Path or string) to a UTF-8 encoded file to read.

The JSON data is first converted to a Python dictionary and the object created using the :meth:from_dict method.

Notice that the source is considered to be JSON data if it is a string and contains {. If you need to use { in a file system path, pass it in as a pathlib.Path instance.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

Source code in src/robot/model/modelobject.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def from_json(cls: Type[T], source: 'str|bytes|TextIO|Path') -> T:
    """Create this object based on JSON data.

    The data is given as the ``source`` parameter. It can be:

    - a string (or bytes) containing the data directly,
    - an open file object where to read the data from, or
    - a path (``pathlib.Path`` or string) to a UTF-8 encoded file to read.

    The JSON data is first converted to a Python dictionary and the object
    created using the :meth:`from_dict` method.

    Notice that the ``source`` is considered to be JSON data if it is
    a string and contains ``{``. If you need to use ``{`` in a file system
    path, pass it in as a ``pathlib.Path`` instance.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.
    """
    try:
        data = JsonLoader().load(source)
    except (TypeError, ValueError) as err:
        raise DataError(f'Loading JSON data failed: {err}')
    return cls.from_dict(data)

from_model(model, name=None, *, defaults=None) classmethod

Create a :class:TestSuite object based on the given model.

:param model: Model to create the suite from. :param name: Deprecated since Robot Framework 6.1. :param defaults: Possible test specific defaults from suite initialization files. New in Robot Framework 6.1.

The model can be created by using the :func:~robot.parsing.parser.parser.get_model function and possibly modified by other tooling in the :mod:robot.parsing module.

Giving suite name is deprecated and users should set it and possible other attributes to the returned suite separately. One easy way is using the :meth:config method like this::

1
suite = TestSuite.from_model(model).config(name='X', doc='Example')

See also :meth:from_file_system and :meth:from_string.

Source code in src/robot/running/model.py 
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
@classmethod
def from_model(cls, model: 'File', name: 'str|None' = None, *,
               defaults: 'TestDefaults|None' = None) -> 'TestSuite':
    """Create a :class:`TestSuite` object based on the given ``model``.

    :param model: Model to create the suite from.
    :param name: Deprecated since Robot Framework 6.1.
    :param defaults: Possible test specific defaults from suite
        initialization files. New in Robot Framework 6.1.

    The model can be created by using the
    :func:`~robot.parsing.parser.parser.get_model` function and possibly
    modified by other tooling in the :mod:`robot.parsing` module.

    Giving suite name is deprecated and users should set it and possible
    other attributes to the returned suite separately. One easy way is using
    the :meth:`config` method like this::

        suite = TestSuite.from_model(model).config(name='X', doc='Example')

    See also :meth:`from_file_system` and :meth:`from_string`.
    """
    from .builder import RobotParser
    suite = RobotParser().parse_model(model, defaults)
    if name is not None:
        # TODO: Remove 'name' in RF 7.
        warnings.warn("'name' argument of 'TestSuite.from_model' is deprecated. "
                      "Set the name to the returned suite separately.")
        suite.name = name
    return suite

from_string(string, *, defaults=None, **config) classmethod

Create a :class:TestSuite object based on the given string.

:param string: String to create the suite from. :param defaults: Possible test specific defaults from suite initialization files. :param config: Configuration parameters for :func:~robot.parsing.parser.parser.get_model used internally.

If suite name or other attributes need to be set, an easy way is using the :meth:config method like this::

1
suite = TestSuite.from_string(string).config(name='X', doc='Example')

New in Robot Framework 6.1. See also :meth:from_model and :meth:from_file_system.

Source code in src/robot/running/model.py 
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
@classmethod
def from_string(cls, string: str, *, defaults: 'TestDefaults|None' = None,
                **config) -> 'TestSuite':
    """Create a :class:`TestSuite` object based on the given ``string``.

    :param string: String to create the suite from.
    :param defaults: Possible test specific defaults from suite
        initialization files.
    :param config: Configuration parameters for
         :func:`~robot.parsing.parser.parser.get_model` used internally.

    If suite name or other attributes need to be set, an easy way is using
    the :meth:`config` method like this::

        suite = TestSuite.from_string(string).config(name='X', doc='Example')

    New in Robot Framework 6.1. See also :meth:`from_model` and
    :meth:`from_file_system`.
    """
    from robot.parsing import get_model
    model = get_model(string, data_only=True, **config)
    return cls.from_model(model, defaults=defaults)

metadata(metadata)

Free suite metadata as a :class:~.metadata.Metadata object.

Source code in src/robot/model/testsuite.py 
208
209
210
211
@setter
def metadata(self, metadata: 'Mapping[str, str]|None') -> Metadata:
    """Free suite metadata as a :class:`~.metadata.Metadata` object."""
    return Metadata(metadata)

name_from_source(source, extension=()) staticmethod

Create suite name based on the given source.

This method is used by Robot Framework itself when it builds suites. External parsers and other tools that want to produce suites with names matching names created by Robot Framework can use this method as well. This method is also used if :attr:name is not set and someone accesses it.

The algorithm is as follows:

  • If the source is None or empty, return an empty string.
  • Get the base name of the source. Read more below.
  • Remove possible prefix separated with __.
  • Convert underscores to spaces.
  • If the name is all lower case, title case it.

The base name of files is got by calling Path.stem__ that drops the file extension. It typically works fine, but gives wrong result if the extension has multiple parts like in tests.robot.zip. That problem can be avoided by giving valid file extension or extensions as the optional extension argument.

Examples::

1
2
3
TestSuite.name_from_source(source)
TestSuite.name_from_source(source, extension='.robot.zip')
TestSuite.name_from_source(source, ('.robot', '.robot.zip'))

__ https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.stem

Source code in src/robot/model/testsuite.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@staticmethod
def name_from_source(source: 'Path|str|None', extension: Sequence[str] = ()) -> str:
    """Create suite name based on the given ``source``.

    This method is used by Robot Framework itself when it builds suites.
    External parsers and other tools that want to produce suites with
    names matching names created by Robot Framework can use this method as
    well. This method is also used if :attr:`name` is not set and someone
    accesses it.

    The algorithm is as follows:

    - If the source is ``None`` or empty, return an empty string.
    - Get the base name of the source. Read more below.
    - Remove possible prefix separated with ``__``.
    - Convert underscores to spaces.
    - If the name is all lower case, title case it.

    The base name of files is got by calling `Path.stem`__ that drops
    the file extension. It typically works fine, but gives wrong result
    if the extension has multiple parts like in ``tests.robot.zip``.
    That problem can be avoided by giving valid file extension or extensions
    as the optional ``extension`` argument.

    Examples::

        TestSuite.name_from_source(source)
        TestSuite.name_from_source(source, extension='.robot.zip')
        TestSuite.name_from_source(source, ('.robot', '.robot.zip'))

    __ https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.stem
    """
    if not source:
        return ''
    if not isinstance(source, Path):
        source = Path(source)
    name = TestSuite._get_base_name(source, extension)
    if '__' in name:
        name = name.split('__', 1)[1] or name
    name = name.replace('_', ' ').strip()
    return name.title() if name.islower() else name

randomize(suites=True, tests=True, seed=None)

Randomizes the order of suites and/or tests, recursively.

:param suites: Boolean controlling should suites be randomized. :param tests: Boolean controlling should tests be randomized. :param seed: Random seed. Can be given if previous random order needs to be re-created. Seed value is always shown in logs and reports.

Source code in src/robot/running/model.py 
693
694
695
696
697
698
699
700
701
702
def randomize(self, suites: bool = True, tests: bool = True,
              seed: 'int|None' = None):
    """Randomizes the order of suites and/or tests, recursively.

    :param suites: Boolean controlling should suites be randomized.
    :param tests: Boolean controlling should tests be randomized.
    :param seed: Random seed. Can be given if previous random order needs
        to be re-created. Seed value is always shown in logs and reports.
    """
    self.visit(Randomizer(suites, tests, seed))

remove_empty_suites(preserve_direct_children=False)

Removes all child suites not containing any tests, recursively.

Source code in src/robot/model/testsuite.py 
414
415
416
def remove_empty_suites(self, preserve_direct_children: bool = False):
    """Removes all child suites not containing any tests, recursively."""
    self.visit(EmptySuiteRemover(preserve_direct_children))

run(settings=None, **options)

Executes the suite based on the given settings or options.

:param settings: :class:~robot.conf.settings.RobotSettings object to configure test execution. :param options: Used to construct new :class:~robot.conf.settings.RobotSettings object if settings are not given. :return: :class:~robot.result.executionresult.Result object with information about executed suites and tests.

If options are used, their names are the same as long command line options except without hyphens. Some options are ignored (see below), but otherwise they have the same semantics as on the command line. Options that can be given on the command line multiple times can be passed as lists like variable=['VAR1:value1', 'VAR2:value2']. If such an option is used only once, it can be given also as a single string like variable='VAR:value'.

Additionally, listener option allows passing object directly instead of listener name, e.g. run('tests.robot', listener=Listener()).

To capture stdout and/or stderr streams, pass open file objects in as special keyword arguments stdout and stderr, respectively.

Only options related to the actual test execution have an effect. For example, options related to selecting or modifying test cases or suites (e.g. --include, --name, --prerunmodifier) or creating logs and reports are silently ignored. The output XML generated as part of the execution can be configured, though. This includes disabling it with output=None.

Example::

1
2
3
4
5
6
stdout = StringIO()
result = suite.run(variable='EXAMPLE:value',
                   output='example.xml',
                   exitonfailure=True,
                   stdout=stdout)
print(result.return_code)

To save memory, the returned :class:~robot.result.executionresult.Result object does not have any information about the executed keywords. If that information is needed, the created output XML file needs to be read using the :class:~robot.result.resultbuilder.ExecutionResult factory method.

See the :mod:package level <robot.running> documentation for more examples, including how to construct executable test suites and how to create logs and reports based on the execution results.

See the :func:robot.run <robot.run.run> function for a higher-level API for executing tests in files or directories.

Source code in src/robot/running/model.py 
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
def run(self, settings=None, **options):
    """Executes the suite based on the given ``settings`` or ``options``.

    :param settings: :class:`~robot.conf.settings.RobotSettings` object
        to configure test execution.
    :param options: Used to construct new
        :class:`~robot.conf.settings.RobotSettings` object if ``settings``
        are not given.
    :return: :class:`~robot.result.executionresult.Result` object with
        information about executed suites and tests.

    If ``options`` are used, their names are the same as long command line
    options except without hyphens. Some options are ignored (see below),
    but otherwise they have the same semantics as on the command line.
    Options that can be given on the command line multiple times can be
    passed as lists like ``variable=['VAR1:value1', 'VAR2:value2']``.
    If such an option is used only once, it can be given also as a single
    string like ``variable='VAR:value'``.

    Additionally, listener option allows passing object directly instead of
    listener name, e.g. ``run('tests.robot', listener=Listener())``.

    To capture stdout and/or stderr streams, pass open file objects in as
    special keyword arguments ``stdout`` and ``stderr``, respectively.

    Only options related to the actual test execution have an effect.
    For example, options related to selecting or modifying test cases or
    suites (e.g. ``--include``, ``--name``, ``--prerunmodifier``) or
    creating logs and reports are silently ignored. The output XML
    generated as part of the execution can be configured, though. This
    includes disabling it with ``output=None``.

    Example::

        stdout = StringIO()
        result = suite.run(variable='EXAMPLE:value',
                           output='example.xml',
                           exitonfailure=True,
                           stdout=stdout)
        print(result.return_code)

    To save memory, the returned
    :class:`~robot.result.executionresult.Result` object does not
    have any information about the executed keywords. If that information
    is needed, the created output XML file needs to be read  using the
    :class:`~robot.result.resultbuilder.ExecutionResult` factory method.

    See the :mod:`package level <robot.running>` documentation for
    more examples, including how to construct executable test suites and
    how to create logs and reports based on the execution results.

    See the :func:`robot.run <robot.run.run>` function for a higher-level
    API for executing tests in files or directories.
    """
    from .namespace import IMPORTER
    from .signalhandler import STOP_SIGNAL_MONITOR
    from .suiterunner import SuiteRunner

    with LOGGER:
        if not settings:
            settings = RobotSettings(options)
            LOGGER.register_console_logger(**settings.console_output_config)
        with pyloggingconf.robot_handler_enabled(settings.log_level):
            with STOP_SIGNAL_MONITOR:
                IMPORTER.reset()
                output = Output(settings)
                runner = SuiteRunner(output, settings)
                self.visit(runner)
            output.close(runner.result)
    return runner.result

set_tags(add=(), remove=(), persist=False)

Add and/or remove specified tags to the tests in this suite.

:param add: Tags to add as a list or, if adding only one, as a single string. :param remove: Tags to remove as a list or as a single string. Can be given as patterns where * and ? work as wildcards. :param persist: Add/remove specified tags also to new tests added to this suite in the future.

Source code in src/robot/model/testsuite.py 
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
def set_tags(self, add: Sequence[str] = (), remove: Sequence[str] = (),
             persist: bool = False):
    """Add and/or remove specified tags to the tests in this suite.

    :param add: Tags to add as a list or, if adding only one,
        as a single string.
    :param remove: Tags to remove as a list or as a single string.
        Can be given as patterns where ``*`` and ``?`` work as wildcards.
    :param persist: Add/remove specified tags also to new tests added
        to this suite in the future.
    """
    setter = TagSetter(add, remove)
    self.visit(setter)
    if persist:
        self._my_visitors.append(setter)

to_json(file=None, *, ensure_ascii=False, indent=0, separators=(',', ':'))

Serialize this object into JSON.

The object is first converted to a Python dictionary using the :meth:to_dict method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data to, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json__ module. Notice that the defaults differ from what json uses.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

__ https://docs.python.org/3/library/json.html

Source code in src/robot/model/modelobject.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def to_json(self, file: 'None|TextIO|Path|str' = None, *,
            ensure_ascii: bool = False, indent: int = 0,
            separators: 'tuple[str, str]' = (',', ':')) -> 'str|None':
    """Serialize this object into JSON.

    The object is first converted to a Python dictionary using the
    :meth:`to_dict` method and then the dictionary is converted to JSON.

    The ``file`` parameter controls what to do with the resulting JSON data.
    It can be:

    - ``None`` (default) to return the data as a string,
    - an open file object where to write the data to, or
    - a path (``pathlib.Path`` or string) to a file where to write
      the data using UTF-8 encoding.

    JSON formatting can be configured using optional parameters that
    are passed directly to the underlying json__ module. Notice that
    the defaults differ from what ``json`` uses.

    With ``robot.running`` model objects new in Robot Framework 6.1,
    with ``robot.result`` new in Robot Framework 7.0.

    __ https://docs.python.org/3/library/json.html
    """
    return JsonDumper(ensure_ascii=ensure_ascii, indent=indent,
                      separators=separators).dump(self.to_dict(), file)

validate_execution_mode()

Validate that suite execution mode is set consistently.

Raise an exception if the execution mode is not set (i.e. the :attr:rpa attribute is None) and child suites have conflicting execution modes.

The execution mode is returned. New in RF 6.1.1.

Source code in src/robot/model/testsuite.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
def validate_execution_mode(self) -> 'bool|None':
    """Validate that suite execution mode is set consistently.

    Raise an exception if the execution mode is not set (i.e. the :attr:`rpa`
    attribute is ``None``) and child suites have conflicting execution modes.

    The execution mode is returned. New in RF 6.1.1.
    """
    if self.rpa is None:
        rpa = name = None
        for suite in self.suites:
            suite.validate_execution_mode()
            if rpa is None:
                rpa = suite.rpa
                name = suite.full_name
            elif rpa is not suite.rpa:
                mode1, mode2 = ('tasks', 'tests') if rpa else ('tests', 'tasks')
                raise DataError(
                    f"Conflicting execution modes: Suite '{name}' has {mode1} but "
                    f"suite '{suite.full_name}' has {mode2}. Resolve the conflict "
                    f"or use '--rpa' or '--norpa' options to set the execution "
                    f"mode explicitly."
                )
        self.rpa = rpa
    return self.rpa

visit(visitor)

:mod:Visitor interface <robot.model.visitor> entry-point.

Source code in src/robot/model/testsuite.py 
418
419
420
def visit(self, visitor: SuiteVisitor):
    """:mod:`Visitor interface <robot.model.visitor>` entry-point."""
    visitor.visit_suite(self)