Skip to content

robot.model.testsuite

TestSuite 

1
2
3
4
5
6
7
8
TestSuite(
    name: str = "",
    doc: str = "",
    metadata: Mapping[str, str] | None = None,
    source: Path | str | None = None,
    rpa: bool | None = False,
    parent: TestSuite[KW, TC] | None = None,
)

Bases: ModelObject, Generic[KW, TC]

Base model for single suite.

Extended by :class:robot.running.model.TestSuite and :class:robot.result.model.TestSuite.

Source code in src/robot/model/testsuite.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def __init__(self, name: str = '',
             doc: str = '',
             metadata: 'Mapping[str, str]|None' = None,
             source: 'Path|str|None' = None,
             rpa: 'bool|None' = False,
             parent: 'TestSuite[KW, TC]|None' = None):
    self._name = name
    self.doc = doc
    self.metadata = metadata
    self.source = source
    self.parent = parent
    self.rpa = rpa
    self.suites = []
    self.tests = []
    self._setup: 'KW|None' = None
    self._teardown: 'KW|None' = None
    self._my_visitors: 'list[SuiteVisitor]' = []

from_dict classmethod 

1
from_dict(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.

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 classmethod 

1
from_json(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.

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 

1
2
3
4
5
6
7
to_json(
    file: None = None,
    *,
    ensure_ascii: bool = False,
    indent: int = 0,
    separators: tuple[str, str] = (",", ":")
) -> str

1
2
3
4
5
6
7
to_json(
    file: TextIO | Path | str,
    *,
    ensure_ascii: bool = False,
    indent: int = 0,
    separators: tuple[str, str] = (",", ":")
) -> None

1
2
3
4
5
6
7
to_json(
    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

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)

config 

1
config(**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.

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 

1
copy(**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

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 

1
deepcopy(**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

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)

name_from_source staticmethod 

1
2
3
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::

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

name property writable 

1
name: str

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.

adjust_source 

1
2
3
4
adjust_source(
    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::

 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)

full_name property 

1
full_name: str

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

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

longname property 

1
longname: str

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

metadata 

1
metadata(metadata: Mapping[str, str] | None) -> 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)

validate_execution_mode 

1
validate_execution_mode() -> 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.

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

setup property writable 

1
setup: KW

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.

has_setup property 

1
has_setup: bool

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.

teardown property writable 

1
teardown: KW

Suite teardown.

See :attr:setup for more information.

has_teardown property 

1
has_teardown: bool

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 property 

1
id: str

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.

all_tests property 

1
all_tests: Iterator[TestCase]

Yields all tests this suite and its child suites contain.

New in Robot Framework 6.1.

test_count property 

1
test_count: int

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

set_tags 

1
2
3
4
5
set_tags(
    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.

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)

filter 

1
2
3
4
5
6
filter(
    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::

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

configure 

1
configure(**options)

A shortcut to configure a suite using one method call.

Can only be used with the root test suite.

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

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/model/testsuite.py 
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
def configure(self, **options):
    """A shortcut to configure a suite using one method call.

    Can only be used with the root test suite.

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

    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.
    """
    if self.parent is not None:
        raise ValueError("'TestSuite.configure()' can only be used with "
                         "the root test suite.")
    if options:
        self.visit(SuiteConfigurer(**options))

remove_empty_suites 

1
remove_empty_suites(preserve_direct_children: bool = 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))

visit 

1
visit(visitor: SuiteVisitor)

: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)