Skip to content

builders

TestSuiteBuilder

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.

Source code in src/robot/running/builder/builders.py 
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 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
 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
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
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
192
193
194
195
196
197
198
199
class TestSuiteBuilder:
    """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.
    """

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

    def _get_standard_parsers(self, lang: LanguagesLike,
                              process_curdir: bool) -> 'dict[str, Parser]':
        robot_parser = RobotParser(lang, process_curdir)
        rest_parser = RestParser(lang, process_curdir)
        json_parser = JsonParser()
        return {
            'robot': robot_parser,
            'rst': rest_parser,
            'rest': rest_parser,
            'robot.rst': rest_parser,
            'rbt': json_parser,
            'json': json_parser
        }

    def _get_custom_parsers(self, parsers: Sequence[str]) -> 'dict[str, CustomParser]':
        custom_parsers = {}
        importer = Importer('parser', LOGGER)
        for parser in parsers:
            if isinstance(parser, (str, Path)):
                name, args = split_args_from_name_or_path(parser)
                parser = importer.import_class_or_module(name, args)
            else:
                name = type_name(parser)
            try:
                custom_parser = CustomParser(parser)
            except TypeError as err:
                raise DataError(f"Importing parser '{name}' failed: {err}")
            for ext in custom_parser.extensions:
                custom_parsers[ext] = custom_parser
        return custom_parsers

    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

    def _normalize_paths(self, paths: 'Sequence[Path|str]') -> 'tuple[Path, ...]':
        if not paths:
            raise DataError('One or more source paths required.')
        # Cannot use `Path.resolve()` here because it resolves all symlinks which
        # isn't desired. `Path` doesn't have any methods for normalizing paths
        # so need to use `os.path.normpath()`. Also that _may_ resolve symlinks,
        # but we need to do it for backwards compatibility.
        paths = [Path(normpath(p)).absolute() for p in paths]
        non_existing = [p for p in paths if not p.exists()]
        if non_existing:
            raise DataError(f"Parsing {seq2str(non_existing)} failed: "
                            f"File or directory to execute does not exist.")
        return tuple(paths)

    def _get_parsers(self, paths: 'Sequence[Path]') -> 'dict[str|None, Parser]':
        parsers = {None: NoInitFileDirectoryParser(), **self.custom_parsers}
        robot_parser = self.standard_parsers['robot']
        for ext in chain(self.included_extensions,
                         [self._get_ext(pattern) for pattern in self.included_files],
                         [self._get_ext(pth) for pth in paths if pth.is_file()]):
            ext = ext.lstrip('.').lower()
            if ext not in parsers and ext.replace('.', '').isalnum():
                parsers[ext] = self.standard_parsers.get(ext, robot_parser)
        return parsers

    def _get_ext(self, path: 'str|Path') -> str:
        if not isinstance(path, Path):
            path = Path(path)
        return ''.join(path.suffixes)

    def _validate_not_empty(self, suite: TestSuite, multi_source: bool = False):
        if multi_source:
            for child in suite.suites:
                self._validate_not_empty(child)
        elif not suite.has_tests:
            raise DataError(f"Suite '{suite.name}' contains no tests or tasks.")

__init__(included_suites='DEPRECATED', included_extensions=('.robot', '.rbt', '.robot.rst'), included_files=(), custom_parsers=(), defaults=None, rpa=None, lang=None, allow_empty_suite=False, process_curdir=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.

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(*paths)

: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