Skip to content

robot.running.builder.builders

TestSuiteBuilder 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
TestSuiteBuilder(
    included_suites: str = "DEPRECATED",
    included_extensions: Sequence[str] = (
        ".robot",
        ".rbt",
        ".robot.rst",
    ),
    included_files: Sequence[str] = (),
    custom_parsers: Sequence[str] = (),
    defaults: TestDefaults | None = None,
    rpa: bool | None = None,
    lang: LanguagesLike = None,
    allow_empty_suite: bool = False,
    process_curdir: bool = True,
)

Builder to construct TestSuite objects based on data on the disk.

The :meth:build method constructs executable :class:~robot.running.model.TestSuite objects based on test data files or directories. There are two main use cases for this API:

  • Execute the created suite by using its :meth:~robot.running.model.TestSuite.run method. The suite can be modified before execution if needed.

  • Inspect the suite to see, for example, what tests it has or what tags tests have. This can be more convenient than using the lower level :mod:~robot.parsing APIs.

Both modifying the suite and inspecting what data it contains are easiest done by using the :mod:~robot.model.visitor interface.

This class is part of the public API and should be imported via the :mod:robot.api package. An alternative is using the :meth:TestSuite.from_file_system <robot.running.model.TestSuite.from_file_system> classmethod that uses this class internally.

:param included_suites: This argument used to be used for limiting what suite file to parse. It is deprecated and has no effect starting from RF 6.1. Use the new included_files argument or filter the created suite after parsing instead. :param included_extensions: List of extensions of files to parse. Same as --extension. :param included_files: List of names, paths or directory paths of files to parse. All files are parsed by default. Same as --parse-include. New in RF 6.1. :param custom_parsers: Custom parsers as names or paths (same as --parser) or as parser objects. New in RF 6.1. :param defaults: Possible test specific defaults from suite initialization files. New in RF 6.1. :param rpa: Explicit execution mode. True for RPA and False for test automation. By default, mode is got from data file headers. Same as --rpa or --norpa. :param lang: Additional languages to be supported during parsing. Can be a string matching any of the supported language codes or names, an initialized :class:~robot.conf.languages.Language subclass, a list containing such strings or instances, or a :class:~robot.conf.languages.Languages instance. :param allow_empty_suite: Specify is it an error if the built suite contains no tests. Same as --runemptysuite. :param process_curdir: Control processing the special ${CURDIR} variable. It is resolved already at parsing time by default, but that can be changed by giving this argument False value.

Source code in src/robot/running/builder/builders.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 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
114
115
def __init__(self, included_suites: str = 'DEPRECATED',
             included_extensions: Sequence[str] = ('.robot', '.rbt', '.robot.rst'),
             included_files: Sequence[str] = (),
             custom_parsers: Sequence[str] = (),
             defaults: 'TestDefaults|None' = None,
             rpa: 'bool|None' = None,
             lang: LanguagesLike = None,
             allow_empty_suite: bool = False,
             process_curdir: bool = True):
    """
    :param included_suites:
        This argument used to be used for limiting what suite file to parse.
        It is deprecated and has no effect starting from RF 6.1. Use the
        new ``included_files`` argument or filter the created suite after
        parsing instead.
    :param included_extensions:
        List of extensions of files to parse. Same as ``--extension``.
    :param included_files:
        List of names, paths or directory paths of files to parse. All files
        are parsed by default. Same as `--parse-include`. New in RF 6.1.
    :param custom_parsers:
        Custom parsers as names or paths (same as ``--parser``) or as
        parser objects. New in RF 6.1.
    :param defaults:
        Possible test specific defaults from suite initialization files.
        New in RF 6.1.
    :param rpa:
        Explicit execution mode. ``True`` for RPA and ``False`` for test
        automation. By default, mode is got from data file headers.
        Same as ``--rpa`` or ``--norpa``.
    :param lang:
        Additional languages to be supported during parsing.
        Can be a string matching any of the supported language codes or names,
        an initialized :class:`~robot.conf.languages.Language` subclass,
        a list containing such strings or instances, or a
        :class:`~robot.conf.languages.Languages` instance.
    :param allow_empty_suite:
        Specify is it an error if the built suite contains no tests.
        Same as ``--runemptysuite``.
    :param process_curdir:
        Control processing the special ``${CURDIR}`` variable. It is
        resolved already at parsing time by default, but that can be
        changed by giving this argument ``False`` value.
    """
    self.standard_parsers = self._get_standard_parsers(lang, process_curdir)
    self.custom_parsers = self._get_custom_parsers(custom_parsers)
    self.defaults = defaults
    self.included_extensions = tuple(included_extensions or ())
    self.included_files = tuple(included_files or ())
    self.rpa = rpa
    self.allow_empty_suite = allow_empty_suite
    # TODO: Remove in RF 7.
    if included_suites != 'DEPRECATED':
        warnings.warn("'TestSuiteBuilder' argument 'included_suites' is deprecated "
                      "and has no effect. Use the new 'included_files' argument "
                      "or filter the created suite instead.")

build 

1
build(*paths: Path | str) -> TestSuite

:param paths: Paths to test data files or directories. :return: :class:~robot.running.model.TestSuite instance.

Source code in src/robot/running/builder/builders.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def build(self, *paths: 'Path|str') -> TestSuite:
    """
    :param paths: Paths to test data files or directories.
    :return: :class:`~robot.running.model.TestSuite` instance.
    """
    paths = self._normalize_paths(paths)
    extensions = self.included_extensions + tuple(self.custom_parsers)
    structure = SuiteStructureBuilder(extensions,
                                      self.included_files).build(*paths)
    suite = SuiteStructureParser(self._get_parsers(paths), self.defaults,
                                 self.rpa).parse(structure)
    if not self.allow_empty_suite:
        self._validate_not_empty(suite, multi_source=len(paths) > 1)
    suite.remove_empty_suites(preserve_direct_children=len(paths) > 1)
    return suite