robot.running package

Implements the core test execution logic.

The public API of this module consists of the following objects:

TestSuite for creating an executable test suite structure programmatically.
TestSuiteBuilder for creating executable test suites based on data on a file system. Instead of using this class directly, it is possible to use the TestSuite.from_file_system classmethod that uses it internally.
Classes used by TestSuite, such as TestCase, Keyword and If that are defined in the robot.running.model module. These classes are typically only needed in type hints.
Keyword implementation related classes UserKeyword, LibraryKeyword, InvalidKeyword and their common base class KeywordImplementation. Also these classes are mainly needed in type hints.
TestDefaults that is part of the external parsing API and also typically needed only in type hints.

TestSuite and TestSuiteBuilder can be imported also via the robot.api package.

Note

Prior to Robot Framework 6.1, only some classes in robot.running.model were exposed via robot.running. Keyword implementation related classes are new in Robot Framework 7.0.

Examples

First, let’s assume we have the following test suite in file activate_skynet.robot:

*** Settings ***
Library    OperatingSystem

*** Test Cases ***
Should Activate Skynet
    [Tags]    smoke
    [Setup]    Set Environment Variable    SKYNET    activated
    Environment Variable Should Be Set    SKYNET

We can easily create an executable test suite based on the above file:

from robot.api import TestSuite

suite = TestSuite.from_file_system('path/to/activate_skynet.robot')

That was easy. Let’s next generate the same test suite from scratch:

from robot.api import TestSuite

suite = TestSuite('Activate Skynet')
suite.resource.imports.library('OperatingSystem')
test = suite.tests.create('Should Activate Skynet', tags=['smoke'])
test.setup.config(name='Set Environment Variable', args=['SKYNET', 'activated'])
test.body.create_keyword('Environment Variable Should Be Set', args=['SKYNET'])

Not that complicated either, especially considering the flexibility. Notice that the suite created based on the file could also be edited further using the same API.

Now that we have a test suite ready, let’s execute it and verify that the returned Result object contains correct information:

result = suite.run(output='skynet.xml')

assert result.return_code == 0
assert result.suite.name == 'Activate Skynet'
test = result.suite.tests[0]
assert test.name == 'Should Activate Skynet'
assert test.passed
stats = result.suite.statistics
assert stats.total == 1 and stats.passed == 1 and stats.failed == 0

Running the suite generates a normal output XML file, unless it is disabled by using output=None. Generating log, report, and xUnit files based on the results is possible using the ResultWriter class:

from robot.api import ResultWriter

# Report and xUnit files can be generated based on the result object.
ResultWriter(result).write_results(report='skynet.html', log=None)
# Generating log files requires processing the earlier generated output XML.
ResultWriter('skynet.xml').write_results()

Subpackages

Submodules

robot.running.bodyrunner module

class robot.running.bodyrunner.BodyRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]

class robot.running.bodyrunner.KeywordRunner(context, run=True)[source]

Bases: object

run(data, result, name=None)[source]

robot.running.bodyrunner.ForRunner(context, flavor='IN', run=True, templated=False)[source]

class robot.running.bodyrunner.ForInRunner(context, run=True, templated=False)[source]

Bases: object

flavor = 'IN'

run(data, result)[source]

class robot.running.bodyrunner.ForInRangeRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN RANGE'

class robot.running.bodyrunner.ForInZipRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN ZIP'

class robot.running.bodyrunner.ForInEnumerateRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN ENUMERATE'

class robot.running.bodyrunner.WhileRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]

class robot.running.bodyrunner.IfRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]

class robot.running.bodyrunner.TryRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]

class robot.running.bodyrunner.WhileLimit(on_limit=None, on_limit_message=None)[source]

Bases: object

classmethod create(data, variables)[source]

limit_exceeded()[source]

class robot.running.bodyrunner.DurationLimit(max_time, on_limit, on_limit_message)[source]: Bases: WhileLimit

class robot.running.bodyrunner.IterationCountLimit(max_iterations, on_limit, on_limit_message)[source]: Bases: WhileLimit

class robot.running.bodyrunner.NoLimit(on_limit=None, on_limit_message=None)[source]: Bases: WhileLimit

exception robot.running.bodyrunner.LimitExceeded(on_limit_pass, message)[source]: Bases: ExecutionFailed

robot.running.context module

class robot.running.context.Asynchronous[source]

Bases: object

property event_loop

close_loop()[source]

run_until_complete(coroutine)[source]

is_loop_required(obj)[source]

class robot.running.context.ExecutionContexts[source]

Bases: object

property current

property top

property namespaces

start_suite(suite, namespace, output, dry_run=False)[source]

end_suite()[source]

robot.running.dynamicmethods module

robot.running.dynamicmethods.no_dynamic_method(*args)[source]

class robot.running.dynamicmethods.DynamicMethod(instance)[source]

Bases: object

property name

class robot.running.dynamicmethods.GetKeywordNames(instance)[source]: Bases: DynamicMethod

class robot.running.dynamicmethods.RunKeyword(instance, keyword_name: str | None = None, supports_named_args: bool | None = None)[source]

Bases: DynamicMethod

property supports_named_args: bool

class robot.running.dynamicmethods.GetKeywordDocumentation(instance)[source]: Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordArguments(instance, supports_named_args: bool | None = None)[source]: Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordTypes(instance)[source]: Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordTags(instance)[source]: Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordSource(instance)[source]: Bases: DynamicMethod

robot.running.importer module

class robot.running.importer.Importer[source]

Bases: object

reset()[source]

close_global_library_listeners()[source]

import_library(name, args, alias, variables)[source]

import_resource(path, lang=None)[source]

class robot.running.importer.ImportCache[source]

Bases: object

Keeps track on and optionally caches imported items.

Handles paths in keys case-insensitively on case-insensitive OSes. Unlike dicts, this storage accepts mutable values in keys.

add(key, item=None)[source]

values()[source]

robot.running.invalidkeyword module

Bases: KeywordImplementation

Represents an invalid keyword call.

Keyword may not have been found, there could have been multiple matches, or the keyword call itself could have been invalid.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'INVALID KEYWORD'

create_runner(name, languages=None)[source]

bind(data: Keyword) → InvalidKeyword[source]

embedded

owner

parent

error

class robot.running.invalidkeyword.InvalidKeywordRunner(keyword: InvalidKeyword, name: str | None = None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]

dry_run(data: Keyword, result: Keyword, context, run=True)

robot.running.keywordfinder module

class robot.running.keywordfinder.KeywordFinder(owner: TestLibrary | ResourceFile)[source]

Bases: Generic[K]

find(name: str, count: Literal[1]) → K[source]

find(name: str, count: int | None = None) → list[K]

Find keywords based on the given name.

With normal keywords matching is a case, space and underscore insensitive string comparison and there cannot be more than one match. With keywords accepting embedded arguments, matching is done against the name and there can be multiple matches.

Returns matching keywords as a list, possibly as an empty list, without any validation by default. If the optional count is used, raises a ValueError if the number of found keywords does not match. If count is 1 and exactly one keyword is found, returns that keyword directly and not as a list.

invalidate_cache()[source]

class robot.running.keywordfinder.KeywordCache(keywords: list[K])[source]

Bases: Generic[K]

find(name: str, count: int | None = None) → list[K] | K[source]

robot.running.keywordimplementation module

Bases: ModelObject

Base class for different keyword implementations.

USER_KEYWORD = 'USER KEYWORD'

LIBRARY_KEYWORD = 'LIBRARY KEYWORD'

INVALID_KEYWORD = 'INVALID KEYWORD'

repr_args = ('name', 'args')

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD']

embedded

owner

parent

error

property name: str

property full_name: str

args

Information about accepted arguments.

It would be more correct to use term parameter instead of argument in this context, and this attribute may be renamed accordingly in the future. A forward compatible params attribute exists already now.

property params: ArgumentSpec

Keyword parameter information.

This is a forward compatible alias for args.

property doc: str

property short_doc: str

tags

property lineno: int | None

property private: bool

property source: Path | None

matches(name: str) → bool[source]

Returns true if name matches the keyword name.

With normal keywords matching is a case, space and underscore insensitive string comparison. With keywords accepting embedded arguments, matching is done against the name.

resolve_arguments(args: Sequence[str | Any], named_args: Mapping[str, Any] | None = None, variables=None, languages: LanguagesLike = None) → tuple[list, list][source]

create_runner(name: str | None, languages: LanguagesLike = None) → LibraryKeywordRunner | UserKeywordRunner[source]

bind(data: Keyword) → KeywordImplementation[source]

robot.running.librarykeyword module

class robot.running.librarykeyword.LibraryKeyword(owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: KeywordImplementation

Base class for different library keywords.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'LIBRARY KEYWORD'

property method: Callable[[...], Any]

property lineno: int | None

create_runner(name: str | None, languages: LanguagesLike = None) → LibraryKeywordRunner[source]

resolve_arguments(args: Sequence[str | Any], named_args: Mapping[str, Any] | None = None, variables=None, languages: LanguagesLike = None) → tuple[list, list][source]

bind(data: Keyword) → Self[source]

copy(**attributes) → Self[source]

Return a shallow copy of this object.

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

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.StaticKeyword(method_name: str, owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: LibraryKeyword

Represents a keyword in a static library.

method_name

property method: Callable[[...], Any]: Keyword method.

property source: Path | None

classmethod from_name(name: str, owner: TestLibrary) → StaticKeyword[source]

copy(**attributes) → StaticKeyword[source]

Return a shallow copy of this object.

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

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.DynamicKeyword(owner: DynamicLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: LibraryKeyword

Represents a keyword in a dynamic library.

property method: Callable[[...], Any]: Dynamic run_keyword method.

property source: Path | None

property lineno: int | None

classmethod from_name(name: str, owner: DynamicLibrary) → DynamicKeyword[source]

resolve_arguments(args: Sequence[str | Any], named_args: Mapping[str, Any] | None = None, variables=None, languages: LanguagesLike = None) → tuple[list, list][source]

copy(**attributes) → DynamicKeyword[source]

Return a shallow copy of this object.

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

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

run_keyword

class robot.running.librarykeyword.LibraryInit(owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), positional: list | None = None, named: dict | None = None)[source]

Bases: LibraryKeyword

Represents a library initializer.

positional and named contain arguments used for initializing the library.

property doc: str

property method: Callable[[...], None] | None

Initializer method.

None with module based libraries and when class based libraries do not have __init__.

classmethod from_class(klass) → LibraryInit[source]

classmethod null() → LibraryInit[source]

copy(**attributes) → LibraryInit[source]

Return a shallow copy of this object.

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

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.KeywordCreator(name: str, library: TestLibrary | None = None)[source]

Bases: Generic[K]

keyword_class: type[K]

property instance: Any

create(**extra) → K[source]

get_name() → str[source]

get_args() → ArgumentSpec[source]

get_doc() → str[source]

get_tags() → list[str][source]

class robot.running.librarykeyword.StaticKeywordCreator(name: str, library: TestLibrary)[source]

Bases: KeywordCreator[StaticKeyword]

keyword_class: alias of StaticKeyword

get_name() → str[source]

get_args() → ArgumentSpec[source]

get_doc() → str[source]

get_tags() → list[str][source]

class robot.running.librarykeyword.DynamicKeywordCreator(name: str, library: TestLibrary | None = None)[source]

Bases: KeywordCreator[DynamicKeyword]

keyword_class: alias of DynamicKeyword

library: DynamicLibrary

get_name() → str[source]

get_args() → ArgumentSpec[source]

get_doc() → str[source]

get_tags() → list[str][source]

class robot.running.librarykeyword.LibraryInitCreator(method: Callable[[...], None] | None)[source]

Bases: KeywordCreator[LibraryInit]

keyword_class: alias of LibraryInit

create(**extra) → LibraryInit[source]

get_name() → str[source]

get_args() → ArgumentSpec[source]

get_doc() → str[source]

get_tags() → list[str][source]

robot.running.librarykeywordrunner module

class robot.running.librarykeywordrunner.LibraryKeywordRunner(keyword: LibraryKeyword, name: str | None = None, languages=None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]

dry_run(data: Keyword, result: Keyword, context)[source]

class robot.running.librarykeywordrunner.EmbeddedArgumentsRunner(keyword: LibraryKeyword, name: str)[source]: Bases: LibraryKeywordRunner

class robot.running.librarykeywordrunner.RunKeywordRunner(keyword: LibraryKeyword, execute_in_dry_run=False)[source]: Bases: LibraryKeywordRunner

robot.running.libraryscopes module

class robot.running.libraryscopes.Scope(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

GLOBAL = 1

SUITE = 2

TEST = 3

class robot.running.libraryscopes.ScopeManager(library: TestLibrary)[source]

Bases: object

classmethod for_library(library)[source]

start_suite()[source]

end_suite()[source]

start_test()[source]

end_test()[source]

close_global_listeners()[source]

register_listeners()[source]

unregister_listeners(close=False)[source]

class robot.running.libraryscopes.GlobalScopeManager(library: TestLibrary)[source]

Bases: ScopeManager

start_suite()[source]

end_suite()[source]

close_global_listeners()[source]

class robot.running.libraryscopes.SuiteScopeManager(library)[source]

Bases: ScopeManager

start_suite()[source]

end_suite()[source]

class robot.running.libraryscopes.TestScopeManager(library)[source]

Bases: SuiteScopeManager

start_test()[source]

end_test()[source]

robot.running.model module

Module implementing test execution related model objects.

When tests are executed by Robot Framework, a TestSuite structure using classes defined in this module is created by 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 TestSuite object is executed by calling its run() method as shown in the example in the 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 TestSuite class is exposed via the robot.api package. If other classes are needed, they can be imported from robot.running.

Bases: BaseBody[Keyword, For, While, If, Try, Var, Return, Continue, Break, model.Message, Error]

break_class: alias of Break

continue_class: alias of Continue

error_class: alias of Error

for_class: alias of For

if_class: alias of If

keyword_class: alias of Keyword

return_class: alias of Return

try_class: alias of Try

var_class: alias of Var

while_class: alias of While

class robot.running.model.Branches(branch_class: Type[IT], parent: TestSuite | TestCase | UserKeyword | For | ForIteration | If | IfBranch | Try | TryBranch | While | WhileIteration | Keyword | Var | Return | Continue | Break | Error | None = None, items: Iterable[IT | DataDict] = ())[source]: Bases: BaseBranches[Keyword, For, While, If, Try, Var, Return, Continue, Break, model.Message, Error, IT]

class robot.running.model.WithSource[source]

Bases: object

parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None

property source: Path | None

class robot.running.model.Argument(name: str | None, value: Any)[source]

Bases: object

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.

Parameters:

name – Argument name. If None, argument is considered positional.
value – Argument value.

Bases: 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 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 named_args separately and use 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.

named_args

lineno

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

run(result, context, run=True, templated=None)[source]

Bases: ForIteration, WithSource

body_class: alias of Body

lineno

error

Bases: For, WithSource

body_class: alias of Body

lineno

error

classmethod from_dict(data: Dict[str, Any]) → For[source]

Create this object based on data in a dictionary.

Data can be got from the 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.

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

run(result, context, run=True, templated=False)[source]

get_iteration(assign: Mapping[str, str] | None = None) → ForIteration[source]

Bases: WhileIteration, WithSource

body_class: alias of Body

lineno

error

Bases: While, WithSource

body_class: alias of Body

lineno

error

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

run(result, context, run=True, templated=False)[source]

get_iteration() → WhileIteration[source]

Bases: IfBranch, WithSource

body_class: alias of Body

lineno

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: If, WithSource

branch_class: alias of IfBranch

branches_class: alias of Branches[IfBranch]

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: TryBranch, WithSource

body_class: alias of Body

lineno

classmethod from_dict(data: Dict[str, Any]) → TryBranch[source]

Create this object based on data in a dictionary.

Data can be got from the 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.

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Try, WithSource

branch_class: alias of TryBranch

branches_class: alias of Branches[TryBranch]

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Var, WithSource

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Return, WithSource

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Continue, WithSource

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Break, WithSource

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: Error, WithSource

lineno

error

run(result, context, run=True, templated=False)[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

class robot.running.model.TestCase(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)[source]

Bases: TestCase[Keyword]

Represents a single executable test case.

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

body_class

Internal usage only.

alias of Body

fixture_class

Internal usage only.

alias of Keyword

template

error

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

body: Test body as a Body object.

Bases: TestSuite[Keyword, TestCase]

Represents a single executable test suite.

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

test_class

Internal usage only.

alias of TestCase

fixture_class

Internal usage only.

alias of Keyword

resource: 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.

classmethod from_file_system(*paths: Path | str, **config) → TestSuite[source]

Create a TestSuite object based on the given paths.

Parameters:

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

See also from_model() and from_string().

classmethod from_model(model: File, name: str | None = None, *, defaults: TestDefaults | None = None) → TestSuite[source]

Create a TestSuite object based on the given model.

Parameters:

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

The model can be created by using the get_model() function and possibly modified by other tooling in the 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 config() method like this:

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

classmethod from_string(string: str, *, defaults: TestDefaults | None = None, **config) → TestSuite[source]

Create a TestSuite object based on the given string.

Parameters:

string – String to create the suite from.
defaults – Possible test specific defaults from suite initialization files.
config – Configuration parameters for get_model() used internally.

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

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

New in Robot Framework 6.1. See also from_model() and from_file_system().

configure(randomize_suites: bool = False, randomize_tests: bool = False, randomize_seed: int | None = None, **options)[source]

A shortcut to configure a suite using one method call.

Can only be used with the root test suite.

Parameters:

randomize_xxx – Passed to randomize().
options – Passed to SuiteConfigurer that will then set suite attributes, call filter(), etc. as needed.

Example:

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

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

randomize(suites: bool = True, tests: bool = True, seed: int | None = None)[source]

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

Parameters:

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

suites

run(settings=None, **options)[source]

Executes the suite based on the given settings or options.

Parameters:

settings – RobotSettings object to configure test execution.
options – Used to construct new RobotSettings object if settings are not given.

Returns:

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 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 ExecutionResult factory method.

See the package level 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 robot.run function for a higher-level API for executing tests in files or directories.

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

robot.running.namespace module

class robot.running.namespace.Namespace(variables, suite, resource, languages)[source]

Bases: object

property libraries

handle_imports()[source]

import_resource(name, overwrite=True)[source]

import_variables(name, args, overwrite=False)[source]

import_library(name, args=(), alias=None, notify=True)[source]

set_search_order(new_order)[source]

start_test()[source]

end_test()[source]

start_suite()[source]

end_suite(suite)[source]

start_user_keyword()[source]

end_user_keyword()[source]

get_library_instance(name)[source]

get_library_instances()[source]

reload_library(name_or_instance)[source]

get_runner(name, recommend_on_failure=True)[source]

class robot.running.namespace.KeywordStore(suite_file, languages)[source]

Bases: object

get_library(name_or_instance)[source]

get_runner(name, recommend=True)[source]

class robot.running.namespace.KeywordRecommendationFinder(*owners)[source]

Bases: object

recommend_similar_keywords(name, message)[source]: Return keyword names similar to name.

static format_recommendations(message, recommendations)[source]

robot.running.outputcapture module

class robot.running.outputcapture.OutputCapturer(library_import=False)[source]

Bases: object

start()[source]

stop()[source]

class robot.running.outputcapture.StreamCapturer(stdout=True)[source]

Bases: object

release()[source]

robot.running.randomizer module

class robot.running.randomizer.Randomizer(randomize_suites=True, randomize_tests=True, seed=None)[source]

Bases: SuiteVisitor

start_suite(suite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_test(test)[source]

Implements traversing through tests.

Can be overridden to allow modifying the passed in test without calling start_test() or end_test() nor visiting the body of the test.

visit_keyword(kw)[source]

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting the body of the keyword

robot.running.resourcemodel module

class robot.running.resourcemodel.ResourceFile(source: Path | str | None = None, owner: TestSuite | None = None, doc: str = '')[source]

Bases: ModelObject

Represents a resource file.

repr_args = ('source',)

owner

doc

keyword_finder

property source: Path | None

property name: str | None

Resource file name.

None if resource file is part of a suite or if it does not have source, name of the source file without the extension otherwise.

imports

variables

keywords

classmethod from_file_system(path: Path | str, **config) → ResourceFile[source]

Create a ResourceFile object based on the give path.

Parameters:

path – File path where to read the data from.
config – Configuration parameters for ResourceFileBuilder class that is used internally for building the suite.

New in Robot Framework 6.1. See also from_string() and from_model().

classmethod from_string(string: str, **config) → ResourceFile[source]

Create a ResourceFile object based on the given string.

Parameters:

string – String to create the resource file from.
config – Configuration parameters for get_resource_model() used internally.

New in Robot Framework 6.1. See also from_file_system() and from_model().

classmethod from_model(model: File) → ResourceFile[source]

Create a ResourceFile object based on the given model.

Parameters:: model – Model to create the suite from.

The model can be created by using the get_resource_model() function and possibly modified by other tooling in the robot.parsing module.

New in Robot Framework 6.1. See also from_file_system() and from_string().

find_keywords(name: str, count: Literal[1]) → UserKeyword[source]
find_keywords(name: str, count: int | None = None) → list[UserKeyword]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

Bases: KeywordImplementation

Represents a user keyword.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'USER KEYWORD'

fixture_class: alias of Keyword

timeout

args

body

property setup: Keyword

User keyword setup as a Keyword object.

New in Robot Framework 7.0.

property has_setup: bool

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

See has_teardown for more information. New in Robot Framework 7.0.

property teardown: Keyword: User keyword teardown as a Keyword object.

property has_teardown: bool

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

A difference between using if kw.has_teardown: and if kw.teardown: is that accessing the teardown attribute creates a Keyword object representing the teardown even when the user keyword actually does not have one. This can have an effect on memory usage.

New in Robot Framework 6.1.

create_runner(name: str | None, languages: LanguagesLike = None) → UserKeywordRunner | EmbeddedArgumentsRunner[source]

bind(data: Keyword) → UserKeyword[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

class robot.running.resourcemodel.Variable(name: str = '', value: Sequence[str] = (), separator: str | None = None, owner: ResourceFile | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: ModelObject

repr_args = ('name', 'value', 'separator')

property source: Path | None

report_error(message: str, level: str = 'ERROR')[source]

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

class robot.running.resourcemodel.Import(type: Literal['LIBRARY', 'RESOURCE', 'VARIABLES'], name: str, args: Sequence[str] = (), alias: str | None = None, owner: ResourceFile | None = None, lineno: int | None = None)[source]

Bases: ModelObject

Represents library, resource file or variable file import.

repr_args = ('type', 'name', 'args', 'alias')

LIBRARY = 'LIBRARY'

RESOURCE = 'RESOURCE'

VARIABLES = 'VARIABLES'

property source: Path | None

property directory: Path | None

property setting_name: str

select(library: Any, resource: Any, variables: Any) → Any[source]

report_error(message: str, level: str = 'ERROR')[source]

classmethod from_dict(data) → Import[source]

Create this object based on data in a dictionary.

Data can be got from the 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.

to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

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

class robot.running.resourcemodel.Imports(owner: ResourceFile, imports: Sequence[Import] = ())[source]

Bases: ItemList

library(name: str, args: Sequence[str] = (), alias: str | None = None, lineno: int | None = None) → Import[source]: Create library import.

resource(name: str, lineno: int | None = None) → Import[source]: Create resource import.

variables(name: str, args: Sequence[str] = (), lineno: int | None = None) → Import[source]: Create variables import.

create(*args, **kwargs) → Import[source]

Generic method for creating imports.

Import type specific methods library(), resource() and variables() are recommended over this method.

class robot.running.resourcemodel.Variables(owner: ResourceFile, variables: Sequence[Variable] = ())[source]: Bases: ItemList[Variable]

class robot.running.resourcemodel.UserKeywords(owner: ResourceFile, keywords: Sequence[UserKeyword] = ())[source]

Bases: ItemList[UserKeyword]

append(item: UserKeyword | Dict[str, Any]) → UserKeyword[source]: S.append(value) – append value to the end of the sequence

extend(items: Iterable[UserKeyword | Dict[str, Any]])[source]: S.extend(iterable) – extend sequence by appending elements from the iterable

insert(index: int, item: UserKeyword | Dict[str, Any])[source]: S.insert(index, value) – insert value before index

clear() → None -- remove all items from S[source]

robot.running.runkwregister module

robot.running.signalhandler module

robot.running.status module

class robot.running.status.Failure[source]: Bases: object

class robot.running.status.Exit(failure_mode=False, error_mode=False, skip_teardown_mode=False)[source]

Bases: object

failure_occurred(fatal=False)[source]

error_occurred()[source]

property teardown_allowed

class robot.running.status.SuiteStatus(parent=None, exit_on_failure=False, exit_on_error=False, skip_teardown_on_exit=False)[source]: Bases: _ExecutionStatus

class robot.running.status.TestStatus(parent, test, skip_on_failure=None, rpa=False)[source]

Bases: _ExecutionStatus

test_failed(message=None, error=None)[source]

test_skipped(message)[source]

property skip_on_failure_after_tag_changes

class robot.running.status.TestMessage(status)[source]

Bases: _Message

setup_message = 'Setup failed:\n%s'

teardown_message = 'Teardown failed:\n%s'

setup_skipped_message = '%s'

teardown_skipped_message = '%s'

also_teardown_message = '%s\n\nAlso teardown failed:\n%s'

also_teardown_skip_message = 'Skipped in teardown:\n%s\n\nEarlier message:\n%s'

exit_on_fatal_message = 'Test execution stopped due to a fatal error.'

exit_on_failure_message = 'Failure occurred and exit-on-failure mode is in use.'

exit_on_error_message = 'Error occurred and exit-on-error mode is in use.'

property message

class robot.running.status.SuiteMessage(status)[source]

Bases: _Message

setup_message = 'Suite setup failed:\n%s'

setup_skipped_message = 'Skipped in suite setup:\n%s'

teardown_skipped_message = 'Skipped in suite teardown:\n%s'

teardown_message = 'Suite teardown failed:\n%s'

also_teardown_message = '%s\n\nAlso suite teardown failed:\n%s'

also_teardown_skip_message = 'Skipped in suite teardown:\n%s\n\nEarlier message:\n%s'

class robot.running.status.ParentMessage(status)[source]

Bases: SuiteMessage

setup_message = 'Parent suite setup failed:\n%s'

setup_skipped_message = 'Skipped in parent suite setup:\n%s'

teardown_skipped_message = 'Skipped in parent suite teardown:\n%s'

teardown_message = 'Parent suite teardown failed:\n%s'

also_teardown_message = '%s\n\nAlso parent suite teardown failed:\n%s'

robot.running.statusreporter module

class robot.running.statusreporter.StatusReporter(data, result, context, run=True, suppress=False, implementation=None)[source]: Bases: object

robot.running.suiterunner module

class robot.running.suiterunner.SuiteRunner(output, settings)[source]

Bases: SuiteVisitor

property context

start_suite(data: TestSuite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_suite(suite: TestSuite)[source]: Called when a suite ends. Default implementation does nothing.

visit_test(data: TestCase)[source]

Implements traversing through tests.

Can be overridden to allow modifying the passed in test without calling start_test() or end_test() nor visiting the body of the test.

robot.running.testlibraries module

class robot.running.testlibraries.TestLibrary(code: type | ~types.ModuleType, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: object

Represents imported test library.

property instance: Any

Current library instance.

With module based libraries this is the module itself.

With class based libraries this is an instance of the class. Instances are cleared automatically during execution based on their scope. Accessing this property creates a new instance if needed.

code´ contains the original library code. With module based libraries it is the same as :attr:`instance. With class based libraries it is the library class.

property listeners: list[Any]

property converters: CustomArgumentConverters | None

property doc: str

property doc_format: str

property scope: Scope

source

property version: str

property lineno: int

classmethod from_name(name: str, real_name: str | None = None, args: ~typing.Sequence[str] | None = None, variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → TestLibrary[source]

classmethod from_code(code: type | ~types.ModuleType, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] | None = None, variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → TestLibrary[source]

classmethod from_module(module: ~types.ModuleType, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → TestLibrary[source]

classmethod from_class(klass: type, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] = (), variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → TestLibrary[source]

create_keywords()[source]

find_keywords(name: str, count: Literal[1]) → LibraryKeyword[source]
find_keywords(name: str, count: int | None = None) → list[LibraryKeyword]

copy(name: str) → Self[source]

report_error(message: str, details: str | None = None, level: str = 'ERROR', details_level: str = 'INFO')[source]

class robot.running.testlibraries.ModuleLibrary(code: type | ~types.ModuleType, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: TestLibrary

property scope: Scope

classmethod from_module(module: ~types.ModuleType, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → ModuleLibrary[source]

classmethod from_class(*args, **kws) → TestLibrary[source]

create_keywords()[source]

class robot.running.testlibraries.ClassLibrary(code: type | ~types.ModuleType, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: TestLibrary

property instance: Any

Current library instance.

With module based libraries this is the module itself.

With class based libraries this is an instance of the class. Instances are cleared automatically during execution based on their scope. Accessing this property creates a new instance if needed.

code´ contains the original library code. With module based libraries it is the same as :attr:`instance. With class based libraries it is the library class.

property lineno: int

classmethod from_module(*args, **kws) → TestLibrary[source]

classmethod from_class(klass: type, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] = (), variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) → ClassLibrary[source]

create_keywords()[source]

class robot.running.testlibraries.HybridLibrary(code: type | ~types.ModuleType, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: ClassLibrary

create_keywords()[source]

class robot.running.testlibraries.DynamicLibrary(code: type | ~types.ModuleType, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: ClassLibrary

property supports_named_args: bool

property doc: str

create_keywords()[source]

class robot.running.testlibraries.KeywordCreator(library: TestLibrary, getting_method_failed_level='INFO')[source]

Bases: object

get_keyword_names() → list[str][source]

create_keywords(names: list[str] | None = None)[source]

class robot.running.testlibraries.StaticKeywordCreator(library: TestLibrary, getting_method_failed_level='INFO', excluded_names=None, avoid_properties=False)[source]

Bases: KeywordCreator

get_keyword_names() → list[str][source]

class robot.running.testlibraries.DynamicKeywordCreator(library: DynamicLibrary | HybridLibrary)[source]

Bases: KeywordCreator

library: DynamicLibrary

get_keyword_names() → list[str][source]

robot.running.userkeywordrunner module

class robot.running.userkeywordrunner.UserKeywordRunner(keyword: UserKeyword, name: str | None = None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]

dry_run(data: Keyword, result: Keyword, context)[source]

class robot.running.userkeywordrunner.EmbeddedArgumentsRunner(keyword: UserKeyword, name: str)[source]: Bases: UserKeywordRunner